@semacode/cli 3.9.3 → 3.10.0

package/dist/bin.js

@@ -105,6 +105,16 @@ export async function executarCliPublica(argv = process.argv.slice(2)) {
             if (!execucao) {
                 return emitirFalhaControle(argv, "FATAL_ERROR", "CLI_FATAL_ERROR", "Falha ao executar a CLI da Sema.", 1);
             }
+            try {
+                const doc = JSON.parse(execucao.stdout.trim());
+                if (doc.schemaVersion === "sema.cli.control/v1" && typeof doc.kind === "string" && doc.exitCode === execucao.codigoSaida) {
+                    console.log(execucao.stdout);
+                    return execucao.codigoSaida;
+                }
+            }
+            catch {
+                // nao e um envelope de controle; segue o caminho normal
+            }
             return emitirResultadoCliJsonV1({
                 comando: sintaxe.comando,
                 codigoSaida: execucao.codigoSaida,

package/dist/cliControlError.d.ts

@@ -1,12 +1,17 @@
-export type CategoriaFalhaControleCli = "UNKNOWN_COMMAND" | "ARGUMENT_ERROR" | "FATAL_ERROR";
+export type CategoriaFalhaControleCli = "UNKNOWN_COMMAND" | "ARGUMENT_ERROR" | "CONTRACT_NOT_FOUND" | "FATAL_ERROR";
 export declare class CliControlError extends Error {
     readonly categoria: CategoriaFalhaControleCli;
     readonly codigoPublico: string;
     readonly mensagemPublica: string;
     readonly codigoSaida: number;
-    constructor(categoria: CategoriaFalhaControleCli);
+    readonly detalhes?: Record<string, unknown>;
+    constructor(categoria: CategoriaFalhaControleCli, detalhes?: Record<string, unknown>);
 }
 export declare function erroComandoDesconhecido(): CliControlError;
 export declare function erroArgumentoInvalido(): CliControlError;
+export declare function erroContratoNaoEncontrado(detalhes: {
+    caminhoTentado: string;
+    sugeridos: string[];
+}): CliControlError;
 export declare function erroFatalCli(): CliControlError;
 export declare function ehCliControlError(valor: unknown): valor is CliControlError;

package/dist/cliControlError.js

@@ -1,5 +1,6 @@
 // SEMA-GOVERNED: sema.produto.cli_invocacao_publica.argumentos
 // Descrição: representa falhas públicas de controle sem carregar argv, stack ou caminhos na mensagem.
+const MENSAGEM_CONTRATO_NAO_ENCONTRADO = "Contrato Sema nao encontrado. Consulte os contratos sugeridos no envelope.";
 const DEFINICOES_FALHA_CONTROLE = Object.freeze({
     UNKNOWN_COMMAND: Object.freeze({
         codigoPublico: "CLI_UNKNOWN_COMMAND",
@@ -11,6 +12,11 @@ const DEFINICOES_FALHA_CONTROLE = Object.freeze({
         mensagemPublica: "Argumentos inválidos. Consulte a ajuda do comando.",
         codigoSaida: 1,
     }),
+    CONTRACT_NOT_FOUND: Object.freeze({
+        codigoPublico: "CLI_CONTRACT_NOT_FOUND",
+        mensagemPublica: MENSAGEM_CONTRATO_NAO_ENCONTRADO,
+        codigoSaida: 2,
+    }),
     FATAL_ERROR: Object.freeze({
         codigoPublico: "CLI_FATAL_ERROR",
         mensagemPublica: "Falha ao executar a CLI da Sema.",
@@ -22,7 +28,8 @@ export class CliControlError extends Error {
     codigoPublico;
     mensagemPublica;
     codigoSaida;
-    constructor(categoria) {
+    detalhes;
+    constructor(categoria, detalhes) {
         const definicao = DEFINICOES_FALHA_CONTROLE[categoria];
         super(definicao.mensagemPublica);
         this.name = "CliControlError";
@@ -30,6 +37,7 @@ export class CliControlError extends Error {
         this.codigoPublico = definicao.codigoPublico;
         this.mensagemPublica = definicao.mensagemPublica;
         this.codigoSaida = definicao.codigoSaida;
+        this.detalhes = detalhes;
     }
 }
 export function erroComandoDesconhecido() {
@@ -38,6 +46,9 @@ export function erroComandoDesconhecido() {
 export function erroArgumentoInvalido() {
     return new CliControlError("ARGUMENT_ERROR");
 }
+export function erroContratoNaoEncontrado(detalhes) {
+    return new CliControlError("CONTRACT_NOT_FOUND", detalhes);
+}
 export function erroFatalCli() {
     return new CliControlError("FATAL_ERROR");
 }

package/dist/cliGrammar.js

@@ -10,7 +10,7 @@ const COMANDOS_PUBLICOS = new Set([
     "impacto", "importar", "iniciar", "init", "inspecionar", "instalar-exemplos",
     "interativo", "ir", "pipeline", "profile", "prompt-curto", "prompt-ia",
     "prompt-ia-react", "prompt-ia-sema-primeiro", "prompt-ia-ui", "renomear-semantico",
-    "resumo", "rule-packs", "skill", "starter-ia", "sync", "sync-codex", "testar",
+    "resumo", "rule-packs", "sessao", "skill", "starter-ia", "sync", "sync-codex", "testar",
     "validar", "verificar", "ast",
 ]);
 const TEMPLATES_INICIAR = new Set([
@@ -451,6 +451,7 @@ function validarComandoBasico(comando, args) {
             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 "sessao": return parsearArgumentos(args, { flags: ["--json"], maxPosicionais: 2 }) !== null;
         case "formatar": return parsearArgumentos(args, { flags: ["--check"], maxPosicionais: 1 }) !== null;
         case "inspecionar": {
             const parsed = parsearArgumentos(args, { opcoes: ["--drift", "--cache"], flags: ["--com-drift"], maxPosicionais: 1 });

package/dist/cliHelpTexto.js

@@ -143,6 +143,7 @@ export function criarAjudaRaiz(versao) {
             "sema contexto-ia <arquivo.sema> [--saida <diretorio>] [--json]",
             "sema sync-codex [--json]",
             "sema instalar-exemplos [--json]",
+            "sema sessao [intencao] [entrada] [--json]",
             "sema docs-impacto --intencao <acao> [--arquivo <caminho>] [--criar-ausentes] [--completo] [--json]",
             "sema finalizar-mudanca --intencao <acao> [--arquivo <caminho>] [--doc-lida <caminho>] [--json]",
             "sema author briefing <arquivo.sema> [--json]",

package/dist/cliRuntime.js

@@ -12,7 +12,21 @@ export async function executarCliRuntimeInterno(principalInjetado) {
             ? codigoSaida
             : CODIGO_SAIDA_FATAL_RUNTIME_CLI;
     }
-    catch {
+    catch (erro) {
+        if (typeof erro?.categoria === "string" && erro.categoria) {
+            const cli = erro;
+            const envelope = {
+                schemaVersion: "sema.cli.control/v1",
+                ok: false,
+                kind: cli.categoria,
+                code: cli.codigoPublico,
+                message: cli.mensagemPublica,
+                exitCode: cli.codigoSaida,
+                ...(cli.detalhes ? { details: cli.detalhes } : {}),
+            };
+            console.log(JSON.stringify(envelope, null, 2));
+            return cli.codigoSaida;
+        }
         return CODIGO_SAIDA_FATAL_RUNTIME_CLI;
     }
 }

package/dist/comandoSessao.d.ts

@@ -0,0 +1,34 @@
+export interface SessaoEnvelope {
+    comando: "sessao";
+    sucesso: boolean;
+    workspace: {
+        baseProjeto: string;
+        nomePasta: string;
+        hashContratos: string;
+        cliVersao: string;
+    };
+    frescor: {
+        fresco: boolean;
+        hashArtefato: string | null;
+        hashAtual: string;
+        sugestao: string;
+    };
+    contratos: {
+        total: number;
+        modulos: string[];
+    };
+    intencoes: {
+        intencao: string;
+        categorias: string[];
+        docsBloqueantes: string[];
+        docsRecomendadas: string[];
+    };
+    gates: {
+        drift: string;
+        validar: string;
+        verificar: string;
+        finalizar: string;
+    };
+    proximosPassos: string[];
+}
+export declare function comandoSessao(posicionais: string[], args: string[], emJson: boolean, cwd?: string): Promise<number>;

package/dist/comandoSessao.js

@@ -0,0 +1,86 @@
+// SEMA-GOVERNED: sema.produto.cli_sessao
+// Descricao: comando sessao devolve envelope compacto de abertura governada.
+import path from "node:path";
+import { verificarFrescorArtefatos } from "./index.part04.js";
+import { carregarProjeto } from "./projetoCarregar.js";
+import { resolverDocumentacaoObrigatoria } from "./docs.js";
+export async function comandoSessao(posicionais, args, emJson, cwd = process.cwd()) {
+    const intencao = posicionais[0] ?? args.find((arg) => arg.startsWith("--intencao="))?.split("=")[1] ?? "";
+    const entrada = posicionais[1];
+    const baseProjeto = entrada ? path.resolve(cwd, entrada) : cwd;
+    const contextoProjeto = await carregarProjeto(entrada, cwd, {
+        escopo: "projeto",
+        adiarDescobertaCodigo: true,
+    });
+    const pacoteCli = (await import("../package.json", { with: { type: "json" } })).default;
+    const frescor = await verificarFrescorArtefatos(contextoProjeto.baseProjeto);
+    const modulosNomes = contextoProjeto.modulosSelecionados.map((item) => item.resultado.modulo?.nome ?? path.basename(item.caminho, ".sema"));
+    let categorias = [];
+    let docsBloqueantes = [];
+    let docsRecomendadas = [];
+    if (intencao.trim()) {
+        const impacto = await resolverDocumentacaoObrigatoria({
+            baseProjeto: contextoProjeto.baseProjeto,
+            intencao,
+            arquivosAlvo: [],
+            criarAusentes: false,
+        });
+        categorias = impacto.categorias;
+        docsBloqueantes = impacto.leituraObrigatoria
+            .filter((doc) => doc.obrigatoriedade !== "recomendada" && doc.existe)
+            .map((doc) => doc.relativo);
+        docsRecomendadas = impacto.leituraRecomendada.map((doc) => doc.relativo);
+    }
+    const envelope = {
+        comando: "sessao",
+        sucesso: true,
+        workspace: {
+            baseProjeto: contextoProjeto.baseProjeto,
+            nomePasta: path.basename(contextoProjeto.baseProjeto),
+            hashContratos: frescor.hashAtual,
+            cliVersao: pacoteCli.version,
+        },
+        frescor,
+        contratos: {
+            total: contextoProjeto.modulosSelecionados.length,
+            modulos: modulosNomes.slice(0, 10),
+        },
+        intencoes: {
+            intencao,
+            categorias,
+            docsBloqueantes,
+            docsRecomendadas,
+        },
+        gates: {
+            drift: "sema drift . --escopo projeto --cache fresh --json",
+            validar: "sema validar contratos --json",
+            verificar: "sema verificar contratos --alvo typescript --json",
+            finalizar: 'sema finalizar-mudanca --intencao "<intencao>" --doc-lida <doc> --json',
+        },
+        proximosPassos: [
+            ...(!frescor.fresco ? ["Artefatos stale detectados — rode sema sync-codex --json antes de agir"] : []),
+            ...(docsBloqueantes.length > 0 ? [`Leia antes de agir: ${docsBloqueantes.slice(0, 5).join(", ")}`] : []),
+            ...(intencao.trim() ? ["Siga o protocolo AGENTS.md passo a passo"] : ["Declare --intencao para receber gates especificos"]),
+        ],
+    };
+    if (emJson) {
+        console.log(JSON.stringify(envelope, null, 2));
+        return 0;
+    }
+    console.log(`Sessao Sema — ${envelope.workspace.nomePasta}`);
+    console.log(`  Hash contratos: ${envelope.workspace.hashContratos}`);
+    console.log(`  CLI: ${envelope.workspace.cliVersao}`);
+    console.log(`  Frescor: ${frescor.fresco ? "fresco" : "STALE"} ${!frescor.fresco ? `(${frescor.sugestao})` : ""}`);
+    console.log(`  Contratos: ${envelope.contratos.total}`);
+    if (intencao) {
+        console.log(`  Intencao: ${intencao}`);
+        console.log(`  Categorias: ${categorias.join(", ")}`);
+        console.log(`  Docs bloqueantes: ${docsBloqueantes.length}`);
+        console.log(`  Docs recomendadas: ${docsRecomendadas.length}`);
+    }
+    for (const passo of envelope.proximosPassos) {
+        console.log(`  → ${passo}`);
+    }
+    return 0;
+}
+//# sourceMappingURL=comandoSessao.js.map

package/dist/docs.part01.js

@@ -128,7 +128,7 @@ export async function listarArquivosRecursivo(base, limite = 80) {
 export const REGRAS_DOCUMENTACAO = [
     {
         categoria: "deploy",
-        padroes: [/deploy/, /publicar/, /producao/, /release/, /pipeline/, /\bci\b/, /\bcd\b/, /vercel/, /cloudflare/, /docker/],
+        padroes: [/deploy/, /publicar/, /producao/, /release/, /pipeline/, /\bci\b/, /\bcd\b/, /vercel/, /cloudflare/, /docker/, /edge.?function/i, /\bruntime\b/i, /\blambda\b/i, /\bworker\b/i, /\bserverless\b/i],
         docs: [
             { relativo: "docs/deploy.md", tipo: "runbook", motivo: "runbook de deploy antes de publicar ou alterar pipeline", permitirCriacao: true },
             { relativo: "docs/env.md", tipo: "runbook", motivo: "variaveis, secrets e ambientes usados no deploy", permitirCriacao: true },

package/dist/index.part01.d.ts

@@ -4,7 +4,7 @@ import { type GuiaCapacidadeIaMap } from './agentContextTipos.js';
 import { renderizarCaixaAscii, renderizarSecaoAscii } from './cliHelpTexto.js';
 import { criarBriefingAgente, criarBriefingAgenteContratos, resumirDriftPorModulo } from "./index.part03.js";
 import { type ComandoConsultaDrift, type ModoCacheDrift, type ResolucaoModoCacheDrift } from "./driftCacheModes.js";
-export type Comando = "iniciar" | "init" | "dev" | "sync" | "author" | "profile" | "conteudo" | "interativo" | "descobrir" | "pipeline" | "capabilities" | "validar" | "ast" | "ir" | "compilar" | "gerar" | "testar" | "diagnosticos" | "verificar" | "inspecionar" | "drift" | "impacto" | "renomear-semantico" | "importar" | "doctor" | "formatar" | "ajuda-ia" | "starter-ia" | "sync-codex" | "skill" | "instalar-exemplos" | "rule-packs" | "docs-impacto" | "finalizar-mudanca" | "resumo" | "prompt-curto" | "prompt-ia" | "prompt-ia-ui" | "prompt-ia-react" | "prompt-ia-sema-primeiro" | "exemplos-prompt-ia" | "contexto-ia";
+export type Comando = "iniciar" | "init" | "dev" | "sync" | "author" | "profile" | "conteudo" | "interativo" | "descobrir" | "pipeline" | "capabilities" | "validar" | "ast" | "ir" | "compilar" | "gerar" | "testar" | "diagnosticos" | "verificar" | "inspecionar" | "drift" | "impacto" | "renomear-semantico" | "importar" | "doctor" | "formatar" | "ajuda-ia" | "starter-ia" | "sync-codex" | "skill" | "instalar-exemplos" | "rule-packs" | "docs-impacto" | "finalizar-mudanca" | "resumo" | "sessao" | "prompt-curto" | "prompt-ia" | "prompt-ia-ui" | "prompt-ia-react" | "prompt-ia-sema-primeiro" | "exemplos-prompt-ia" | "contexto-ia";
 export interface ResultadoFormatacaoArquivo {
     caminho: string;
     alterado: boolean;

package/dist/index.part02.js

@@ -84,7 +84,7 @@ export function coletarResumoSemanticoModulo(contexto) {
         efeitos: limitarLista(efeitos, 8),
         erros: limitarLista(erros, 8),
         entidadesAfetadas: limitarLista(entidadesAfetadas, 8),
-        arquivosProvaveis: limitarLista(unicosOrdenados(briefing.oQueTocar), 8),
+        arquivosProvaveis: limitarLista(unicosOrdenados(briefing.oQueTocar.map((item) => relativizarCaminho(item))), 8),
         simbolosRelacionados: limitarLista(unicosOrdenados(briefing.simbolosRelacionados), 8),
         riscosPrincipais: limitarLista(unicosOrdenados(briefing.riscosPrincipais), 6),
         lacunas: limitarLista(unicosOrdenados(briefing.oQueEstaFrouxo), 6),
@@ -96,7 +96,7 @@ export function coletarResumoSemanticoModulo(contexto) {
         consumerSurfaces: limitarLista(unicosOrdenados(briefing.consumerSurfaces ?? []), 8),
         consumerBridges: limitarLista(unicosOrdenados(briefing.consumerBridges ?? []), 8),
         ancoragensVinculo: limitarLista(unicosOrdenados(briefing.ancoragensVinculo ?? []), 8),
-        arquivosProvaveisEditar: limitarLista(unicosOrdenados(briefing.arquivosProvaveisEditar ?? briefing.oQueTocar), 8),
+        arquivosProvaveisEditar: limitarLista(unicosOrdenados((briefing.arquivosProvaveisEditar ?? briefing.oQueTocar).map((item) => relativizarCaminho(item))), 8),
     };
     return modoVerificacaoCodigo === "codigo_completo"
         ? resumo
@@ -357,4 +357,10 @@ Contexto compacto:
 ${resumoTexto}
 `;
 }
+function relativizarCaminho(caminho) {
+    const base = process.cwd();
+    const absoluto = path.resolve(base, caminho);
+    const relativo = path.relative(base, absoluto);
+    return relativo && !relativo.startsWith("..") ? relativo.replace(/[\\/]/g, "/") : caminho.replace(/[\\/]/g, "/");
+}
 //# sourceMappingURL=index.part02.js.map

package/dist/index.part04.d.ts

@@ -2,6 +2,13 @@ import { type GuiaCapacidadeIaMap } from './agentContextTipos.js';
 import { ContextoIaGerado, ResumoSemanticoModuloIa, type ResultadoDriftIa } from "./index.part01.js";
 import type { ResolucaoModoCacheDrift } from "./driftCacheModes.js";
 export declare const ARQUIVOS_RESUMO_PROJETO_IA: readonly ["SEMA_BOOT.md", "SEMA_SMALL_MODEL.md", "SEMA_BRIEF.md", "SEMA_BRIEF.micro.txt", "SEMA_BRIEF.curto.txt", "SEMA_INDEX.json", "AGENT_CONTEXT_PACK.json", "docs/ai-integration.md"];
+export declare function verificarFrescorArtefatos(baseProjeto: string): Promise<{
+    fresco: boolean;
+    hashArtefato: string | null;
+    hashAtual: string;
+    contratosMudaram: boolean;
+    sugestao: string;
+}>;
 export declare function gerarResumoProjetoIa(entrada: string | undefined, pastaSaidaOpcional?: string, escreverNaRaiz?: boolean, analiseDrift?: ResolucaoModoCacheDrift): Promise<{
     geradoEm: string;
     baseProjeto: string;

package/dist/index.part04.js

@@ -1,6 +1,7 @@
 // SEMA-GOVERNED: sema.governanca_ia_contexto, sema.produto.escrita_segura_workspace, sema.produto.governanca_ia.drift.cache.modos
 // Descrição: gera contexto local e grava artefatos somente dentro da base validada.
-import { mkdir } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
 import path from "node:path";
 import { formatarDiagnosticos, gerarRespostaValidacao, temErros, } from "@sema/nucleo";
 import { carregarProjeto, } from "./projeto.js";
@@ -53,6 +54,43 @@ function escolherTopArquivosResumo(modulos, arquivosCodigoDetectados) {
     }
     return { arquivos: [], fonte: "nenhum" };
 }
+async function calcularHashContratos(caminhosContratos, baseProjeto) {
+    const hash = createHash("sha256");
+    const base = baseProjeto ?? (caminhosContratos[0] ? path.dirname(caminhosContratos[0]) : process.cwd());
+    const ordenados = [...caminhosContratos].sort();
+    for (const caminho of ordenados) {
+        const conteudo = await readFile(caminho, "utf8").catch(() => "");
+        const relativo = path.relative(base, caminho).replace(/[\\/]/g, "/");
+        hash.update(relativo);
+        hash.update(":");
+        hash.update(conteudo);
+        hash.update(String.fromCharCode(0));
+    }
+    return hash.digest("hex").slice(0, 16);
+}
+export async function verificarFrescorArtefatos(baseProjeto) {
+    const caminhoIndex = path.join(baseProjeto, "SEMA_INDEX.json");
+    let hashArtefato = null;
+    try {
+        const index = JSON.parse(await readFile(caminhoIndex, "utf8"));
+        hashArtefato = index.hashContratos ?? null;
+    }
+    catch {
+        hashArtefato = null;
+    }
+    const origens = await (await import("./projetoOrigens.js")).resolverOrigensProjeto(baseProjeto, baseProjeto, undefined);
+    const { listarArquivosDeOrigens } = await import("./projetoOrigens.js");
+    const contratos = await listarArquivosDeOrigens(origens);
+    const hashAtual = await calcularHashContratos(contratos, baseProjeto);
+    const fresco = hashArtefato === hashAtual;
+    return {
+        fresco,
+        hashArtefato,
+        hashAtual,
+        contratosMudaram: !fresco,
+        sugestao: fresco ? "" : "Artefatos de contexto estao desatualizados; rode sema sync-codex --json para regenerar.",
+    };
+}
 export async function gerarResumoProjetoIa(entrada, pastaSaidaOpcional, escreverNaRaiz = false, analiseDrift = { modo: "none", executar: false, avisos: [] }) {
     const contextoProjeto = await carregarProjeto(entrada, process.cwd(), {
         escopo: "projeto",
@@ -121,10 +159,13 @@ export async function gerarResumoProjetoIa(entrada, pastaSaidaOpcional, escrever
     const semaBoot = renderizarSemaBoot(agentContextPack);
     const semaSmallModel = renderizarSemaSmallModel(agentContextPack);
     const docAgentesCapacidade = renderizarDocumentoAgentesPorCapacidade(agentContextPack);
+    const caminhosContratos = contextoProjeto.modulosSelecionados.map((item) => item.caminho);
+    const hashContratos = await calcularHashContratos(caminhosContratos, contextoProjeto.baseProjeto);
     const indexJson = {
         comando: "resumo-projeto",
         geradoEm,
         cliVersao: VERSAO_CLI,
+        hashContratos,
         baseProjeto,
         modoVerificacaoCodigo,
         analiseDrift: {
@@ -142,7 +183,10 @@ export async function gerarResumoProjetoIa(entrada, pastaSaidaOpcional, escrever
         entradaCanonica,
         agentContextPack,
         guiaPorCapacidade,
-        topArquivosCodigoDetectados: arquivosCodigoDetectados,
+        topArquivosCodigoDetectados: arquivosCodigoDetectados.map((item) => {
+            const rel = path.relative(contextoProjeto.baseProjeto, item);
+            return rel && !rel.startsWith("..") ? rel.replace(/[\\/]/g, "/") : item.replace(/[\\/]/g, "/");
+        }),
         modulos,
     };
     const micro = [

package/dist/index.part05.js

@@ -14,7 +14,7 @@ import { resolverAnaliseDriftConsultaCli, resolverOpcoesDriftCli } from "./index
 export async function comandoInspecionar(entrada, emJson, cwd = process.cwd(), args = []) {
     const analiseDrift = resolverAnaliseDriftConsultaCli(args, "inspecionar");
     const alvo = entrada ? path.resolve(cwd, entrada) : cwd;
-    const alvoEhArquivo = (await stat(alvo)).isFile();
+    const alvoEhArquivo = (await stat(alvo).catch(() => undefined))?.isFile() ?? false;
     const escopoEstreito = analiseDrift.opcoes.escopo === "arquivo"
         || analiseDrift.opcoes.escopo === "modulo"
         || (analiseDrift.opcoes.escopo === undefined

package/dist/index.part06.js

@@ -291,7 +291,7 @@ export async function comandoResumo(entrada, args, emJson) {
     const escreverNaRaiz = possuiFlag(args, "--raiz");
     const alvo = entrada ? path.resolve(process.cwd(), entrada) : process.cwd();
     const analiseDrift = resolverAnaliseDriftConsultaCli(args, "resumo");
-    const alvoEhArquivo = (await stat(alvo)).isFile();
+    const alvoEhArquivo = (await stat(alvo).catch(() => undefined))?.isFile() ?? false;
     if (alvoEhArquivo) {
         const contexto = await carregarContextoModuloIa(alvo, analiseDrift);
         const resumoSemantico = coletarResumoSemanticoModulo(contexto);

package/dist/index.part08.js

@@ -36,6 +36,11 @@ export async function principal() {
         case "iniciar":
             codigoSaida = await comandoIniciar(cwd, normalizarTemplateIniciar(obterOpcao(resto, "--template")), { force: possuiFlag(resto, "--force"), exemplosCompletos: possuiFlag(resto, "--com-exemplos") });
             break;
+        case "sessao": {
+            const { comandoSessao } = await import("./comandoSessao.js");
+            codigoSaida = await comandoSessao(posicionais, resto, possuiFlag(resto, "--json"), cwd);
+            break;
+        }
         case "author":
             codigoSaida = await comandoAuthor(posicionais, resto, possuiFlag(resto, "--json"));
             break;

package/dist/projetoCarregar.d.ts

@@ -1,2 +1,8 @@
 import type { ContextoProjetoCarregado, OpcoesCarregarProjeto } from './projetoTipos.js';
+export declare class ErroContratoNaoEncontrado extends Error {
+    readonly caminhoTentado: string;
+    readonly sugeridos: string[];
+    constructor(mensagem: string, caminhoTentado: string, sugeridos: string[]);
+    paraControleCli(): import("./cliControlError.js").CliControlError;
+}
 export declare function carregarProjeto(entrada: string | undefined, cwd: string, opcoes?: OpcoesCarregarProjeto): Promise<ContextoProjetoCarregado>;

package/dist/projetoCarregar.js

@@ -1,6 +1,7 @@
 // SEMA-GOVERNED: sema.produto.governanca_ia.contexto, sema.produto.governanca_ia.drift.cache.modos
 // Descrição: orquestra leitura de contratos, compilação e seleção de módulos do projeto.
 import { stat } from 'node:fs/promises';
+import { erroContratoNaoEncontrado } from './cliControlError.js';
 import path from 'node:path';
 import { compilarProjeto, listarArquivosSema } from '@sema/nucleo';
 import { canonicalizarContratosNoProjeto, carregarFechamentoContratosSema, carregarFontesContratos, } from './projetoCatalogo.js';
@@ -19,12 +20,53 @@ function resolverFontesLegadoDeclaradas(configCarregada) {
             .filter((fonte) => Boolean(fonte)))]
         .sort((a, b) => a.localeCompare(b, "pt-BR"));
 }
+export class ErroContratoNaoEncontrado extends Error {
+    caminhoTentado;
+    sugeridos;
+    constructor(mensagem, caminhoTentado, sugeridos) {
+        super(mensagem);
+        this.caminhoTentado = caminhoTentado;
+        this.sugeridos = sugeridos;
+        this.name = "ErroContratoNaoEncontrado";
+    }
+    paraControleCli() {
+        return erroContratoNaoEncontrado({ caminhoTentado: this.caminhoTentado, sugeridos: this.sugeridos });
+    }
+}
+async function sugerirContratosProximos(baseProjeto, nomeArquivo) {
+    const origens = await resolverOrigensProjeto(baseProjeto, baseProjeto, undefined);
+    const encontrados = [];
+    for (const origem of origens) {
+        const arquivos = await listarArquivosDeOrigens([origem]);
+        for (const arquivo of arquivos) {
+            encontrados.push(path.relative(baseProjeto, arquivo).replace(/\\/g, "/"));
+        }
+    }
+    const alvo = nomeArquivo.replace(/\.sema$/i, "").toLowerCase();
+    return encontrados
+        .map((relativo) => ({
+        relativo,
+        pontuacao: relativo.toLowerCase().includes(alvo) ? 0 : 1,
+    }))
+        .sort((a, b) => a.pontuacao - b.pontuacao || a.relativo.localeCompare(b.relativo, "pt-BR"))
+        .map((item) => item.relativo).slice(0, 5);
+}
 export async function carregarProjeto(entrada, cwd, opcoes = {}) {
     const entradaBase = entrada ? path.resolve(cwd, entrada) : cwd;
     const configCarregada = await carregarConfiguracaoProjeto(entradaBase);
     const entradaResolvida = entrada ? path.resolve(cwd, entrada) : await resolverEntradaPadrao(cwd, configCarregada);
+    const infoEntrada = await stat(entradaResolvida).catch(() => undefined);
+    if (!infoEntrada) {
+        const baseSugestao = configCarregada?.baseDiretorio ?? path.dirname(entradaResolvida);
+        const contratosProximos = entradaResolvida.toLowerCase().endsWith(".sema")
+            ? await sugerirContratosProximos(baseSugestao, path.basename(entradaResolvida))
+            : [];
+        throw erroContratoNaoEncontrado({
+            caminhoTentado: entradaResolvida,
+            sugeridos: contratosProximos.slice(0, 5),
+        });
+    }
     const baseProjeto = await resolverBaseProjeto(entradaResolvida, configCarregada);
-    const infoEntrada = await stat(entradaResolvida);
     if (infoEntrada.isFile() && path.extname(entradaResolvida).toLowerCase() !== ".sema") {
         throw new Error(`Entrada de contrato precisa terminar em .sema: ${entradaResolvida}`);
     }

package/dist/saidaCli.d.ts

@@ -1,7 +1,7 @@
 import { type EntradaEnvelopeResultadoCliV1, type EnvelopeResultadoCliV1 } from "./resultadoCli.js";
 export { CODIGO_SAIDA_FATAL_RUNTIME_CLI, SCHEMA_RESULTADO_CLI_V1, criarEnvelopeResultadoCliV1, interpretarPayloadRuntimeCli, type EntradaEnvelopeResultadoCliV1, type EnvelopeResultadoCliV1, type TipoResultadoCliV1, } from "./resultadoCli.js";
 export declare const SCHEMA_CONTROLE_CLI_V1: "sema.cli.control/v1";
-export type TipoControleCli = "HELP" | "UNKNOWN_COMMAND" | "ARGUMENT_ERROR" | "FATAL_ERROR";
+export type TipoControleCli = "HELP" | "UNKNOWN_COMMAND" | "ARGUMENT_ERROR" | "CONTRACT_NOT_FOUND" | "FATAL_ERROR";
 export interface EnvelopeControleJsonV1 {
     readonly schemaVersion: typeof SCHEMA_CONTROLE_CLI_V1;
     readonly ok: boolean;
@@ -9,12 +9,14 @@ export interface EnvelopeControleJsonV1 {
     readonly code: string;
     readonly message: string;
     readonly exitCode: number;
+    readonly details?: Record<string, unknown>;
 }
 export interface EntradaEnvelopeControleJsonV1 {
     readonly categoria: TipoControleCli;
     readonly codigoPublico: string;
     readonly mensagemPublica: string;
     readonly codigoSaida: number;
+    readonly detalhes?: Record<string, unknown>;
 }
 export interface OpcoesInvocacaoPublica {
     readonly resultado: TipoControleCli;

package/dist/saidaCli.js

@@ -7,12 +7,14 @@ const CODIGO_PADRAO = {
     HELP: "CLI_HELP",
     UNKNOWN_COMMAND: "CLI_UNKNOWN_COMMAND",
     ARGUMENT_ERROR: "CLI_ARGUMENT_ERROR",
+    CONTRACT_NOT_FOUND: "CLI_CONTRACT_NOT_FOUND",
     FATAL_ERROR: "CLI_FATAL_ERROR",
 };
 const MENSAGEM_PADRAO = {
     HELP: "Ajuda da CLI Sema.",
     UNKNOWN_COMMAND: "Comando Sema desconhecido.",
     ARGUMENT_ERROR: "Argumentos inválidos. Consulte a ajuda do comando.",
+    CONTRACT_NOT_FOUND: "Contrato Sema nao encontrado. Consulte os detalhes no envelope.",
     FATAL_ERROR: "Falha ao executar a CLI da Sema.",
 };
 const CODIGO_PUBLICO_VALIDO = /^[A-Z][A-Z0-9_]{2,63}$/u;
@@ -75,6 +77,9 @@ export function criarEnvelopeControleJsonV1(entrada) {
         code: normalizarCodigoPublico(entrada.categoria, entrada.codigoPublico),
         message: normalizarMensagemPublica(entrada.categoria, entrada.mensagemPublica),
         exitCode,
+        ...(entrada.detalhes && entrada.categoria === "CONTRACT_NOT_FOUND"
+            ? { details: entrada.detalhes }
+            : {}),
     };
 }
 export function emitirResultadoCliJsonV1(entrada) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semacode/cli",
-  "version": "3.9.3",
+  "version": "3.10.0",
   "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",