@semacode/cli 3.9.2 → 3.9.4

package/README.md

@@ -75,16 +75,16 @@ Unknown commands/subcommands, missing or invalid CLI syntax, and uncaught
 runtime exceptions use the control envelope; structured domain-level failures
 after valid dispatch use `sema.cli.result/v1` with `kind: "DOMAIN_ERROR"`.
 
-## Codex Setup
+## Agent Setup
 
-`AGENTS.md` is the official Sema entrypoint for Codex:
+`AGENTS.md` is the official Sema entrypoint for coding agents:
 
 ```bash
 sema sync-codex --json
 ```
 
-Codex automatically loads `AGENTS.md` as durable repository guidance. See the
-[Codex `AGENTS.md` documentation](https://learn.chatgpt.com/docs/agent-configuration/agents-md).
+Agent tools that read `AGENTS.md` — Claude, Codex, zCode (GLM) and Kimi among
+them — load it as durable repository guidance.
 
 The CLI is the engine and source of truth; `AGENTS.md` is the automatic
 workspace protocol. The Sema skill bootstraps a project that does not have Sema
@@ -107,7 +107,7 @@ If a shell still cannot resolve `sema`, invoke the managed launcher directly:
 On Windows, PowerShell resolves `sema.ps1` from `PATH`, `cmd.exe` resolves
 `sema.cmd`, and `sema-managed.ps1` is the PATH-independent fallback.
 
-## Codex-Native Architecture
+## Architecture
 
 - `AGENTS.md` is the only official entrypoint. `sync-codex` changes only valid
   Sema-managed blocks and preserves malformed or manual content for review.
@@ -149,7 +149,7 @@ sema sync-codex --json
 
 Initialization preserves existing files and rejects symlink or junction
 escapes. Use `--force` only when overwriting the template destinations is an
-explicit human decision; the Codex bootstrap skill never adds it.
+explicit human decision; the bootstrap skill never adds it.
 
 ## Code Generation
 

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/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/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.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.js

@@ -142,7 +142,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/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.2",
+  "version": "3.9.4",
   "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",