@semacode/cli 3.9.4 → 3.11.0

package/README.md

@@ -29,9 +29,15 @@ install or update because existing tasks do not reload their skill catalog.
 
 ```bash
 sema --version
+sema sessao "describe the change" --json
 sema resumo . --curto --drift none
 ```
 
+`sema sessao` opens a governed session with one compact envelope: workspace
+identity and contract hash, artifact freshness with the exact recovery command
+when stale, the blocking and recommended docs for the declared intent, the four
+gate commands, and concrete next steps.
+
 Public Sema is local-only. The CLI runs directly without a Sema login, user
 authorization, product-license check, activation key, token, credits, billing
 service, control panel, or external service credentials. The license governs
@@ -123,6 +129,7 @@ On Windows, PowerShell resolves `sema.ps1` from `PATH`, `cmd.exe` resolves
 ## Local Workflow
 
 ```bash
+sema sessao "describe the change" --json
 sema docs-impacto --intencao "describe the change" --arquivo contratos/app.sema --json
 sema inspecionar contratos/app.sema --drift none --json
 sema drift contratos/app.sema --escopo modulo --cache fresh --json

package/dist/agentEntryPoints.js

@@ -147,7 +147,7 @@ Você está em um projeto governado por Sema. O contrato semântico vem antes de
 ## Primeira ação
 
 1. Confirme \`AGENTS.md\` na raiz e rode \`sema --version\`. Se o shell não localizar o comando, use \`$HOME/.sema/bin/sema\` no macOS/Linux; no Windows, PowerShell usa \`sema.ps1\` no PATH, cmd.exe usa \`sema.cmd\`, e o fallback absoluto é \`& "$env:SystemRoot\\System32\\WindowsPowerShell\\v1.0\\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\\.sema\\bin\\sema-managed.ps1" --version\`. Só então declare a CLI indisponível.
-2. Use a CLI local diretamente para ler o workspace: \`sema resumo --drift none\`, \`sema docs-impacto\`, \`sema inspecionar --drift none\`, \`sema drift --cache fresh\` e \`sema impacto\`. Na 3.0.0, \`sema --version\` continua texto SemVer exato; com \`--json\`, help e falhas de controle usam \`sema.cli.control/v1\`, enquanto comandos sintaticamente válidos usam o envelope exato de oito campos \`sema.cli.result/v1\`, com o resultado aninhado em \`payload\` e \`ok\` separado do veredito de domínio desse payload.
+2. Use a CLI local diretamente para ler o workspace: \`sema sessao "<intencao>" --json\` na abertura (identidade, frescor, docs bloqueantes e gates em um envelope), depois \`sema resumo --drift none\`, \`sema docs-impacto\`, \`sema inspecionar --drift none\`, \`sema drift --cache fresh\` e \`sema impacto\`. Na 3.0.0, \`sema --version\` continua texto SemVer exato; com \`--json\`, help e falhas de controle usam \`sema.cli.control/v1\`, enquanto comandos sintaticamente válidos usam o envelope exato de oito campos \`sema.cli.result/v1\`, com o resultado aninhado em \`payload\` e \`ok\` separado do veredito de domínio desse payload.
 3. Se não estiver claro qual profile, workflow, pipeline, gerador ou adapter usar, rode \`sema descobrir recomendar --intencao "<objetivo>" --json\`; não execute automaticamente uma recomendação ambígua.
 4. Não use fonte externa de workspace para substituir a CLI local quando ela estiver operacional.
 5. Este boot é para workspace local em disco; se não houver workspace local, pare bloqueado em vez de inventar caminho.
@@ -442,16 +442,17 @@ Este workspace é governado por Sema. Antes de qualquer ação em código, contr
 
 1. Leia \`${ARQUIVO_SEMA_BOOT}\`.
 2. Rode \`sema --version\`; se o shell falhar, use \`$HOME/.sema/bin/sema\` no macOS/Linux. No Windows, PowerShell usa \`sema.ps1\` no PATH e cmd.exe usa \`sema.cmd\`; use \`& "$env:SystemRoot\\System32\\WindowsPowerShell\\v1.0\\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\\.sema\\bin\\sema-managed.ps1" --version\` como fallback absoluto. Só então pare e peça instalação ou reparo.
-3. Use diretamente a CLI local: \`sema resumo --drift none\`, \`sema docs-impacto\`, \`sema inspecionar --drift none\`, \`sema drift --cache fresh\` e \`sema impacto\`. Na 3.0.0, \`sema --version\` continua texto SemVer exato; com \`--json\`, help e falhas de controle usam \`sema.cli.control/v1\`, enquanto comandos sintaticamente válidos usam o envelope exato de oito campos \`sema.cli.result/v1\`, com resultado em \`payload\` e \`ok\` distinto do veredito de domínio do payload.
-4. Quando a capacidade correta não estiver clara, use \`sema descobrir recomendar --intencao "<objetivo>" --json\`; não autoexecute resultado ambíguo.
-5. Não use fonte externa de workspace para substituir a CLI local quando ela estiver operacional.
-6. Chame docs-impacto com a intenção declarada antes de agir.
-7. Chame inspecionar no contrato \`.sema\` aplicável.
-8. Para módulo novo com contrato validado, gere o andaime com \`sema compilar <contrato> --alvo <alvoPadrao>\`, preencha a implementação real mantendo \`impl\`/\`vinculos\` e feche com \`sema verificar\`.
-9. Antes de editar código existente, rode \`sema drift --cache fresh\` e impacto.
-10. Antes de criar ou editar \`.sema\`, use exemplos oficiais.
-11. Ao concluir mudança de contrato, rode validar.
-12. Antes de finalizar, use finalizar-mudanca com as docs lidas.
+3. Abra a sessão com \`sema sessao "<intencao>" --json\`: devolve identidade do workspace, hash dos contratos, frescor dos artefatos gerados, docs bloqueantes da intenção e os gates do ciclo. Se \`frescor.fresco\` for falso, rode o \`sync-codex\` sugerido antes de agir.
+4. Use diretamente a CLI local: \`sema resumo --drift none\`, \`sema docs-impacto\`, \`sema inspecionar --drift none\`, \`sema drift --cache fresh\` e \`sema impacto\`. Na 3.0.0, \`sema --version\` continua texto SemVer exato; com \`--json\`, help e falhas de controle usam \`sema.cli.control/v1\`, enquanto comandos sintaticamente válidos usam o envelope exato de oito campos \`sema.cli.result/v1\`, com resultado em \`payload\` e \`ok\` distinto do veredito de domínio do payload.
+5. Quando a capacidade correta não estiver clara, use \`sema descobrir recomendar --intencao "<objetivo>" --json\`; não autoexecute resultado ambíguo.
+6. Não use fonte externa de workspace para substituir a CLI local quando ela estiver operacional.
+7. Chame docs-impacto com a intenção declarada antes de agir.
+8. Chame inspecionar no contrato \`.sema\` aplicável.
+9. Para módulo novo com contrato validado, gere o andaime com \`sema compilar <contrato> --alvo <alvoPadrao>\`, preencha a implementação real mantendo \`impl\`/\`vinculos\` e feche com \`sema verificar\`.
+10. Antes de editar código existente, rode \`sema drift --cache fresh\` e impacto.
+11. Antes de criar ou editar \`.sema\`, use exemplos oficiais.
+12. Ao concluir mudança de contrato, rode validar.
+13. Antes de finalizar, use finalizar-mudanca com as docs lidas.
 
 É proibido substituir esse fluxo por leitura manual de \`AGENTS.md\`, \`README.md\`, busca local por arquivos, inferência pelo nome do projeto, bom senso ou ferramenta não citada nesta lista.
 

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/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/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.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: {

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/docs/cli.md

@@ -148,6 +148,7 @@ code, contracts, workflows, release scripts, or operational docs:
 
 ```bash
 sema --version
+sema sessao "describe the change" --json
 sema resumo --drift none
 sema docs-impacto --intencao "describe the change" --json
 sema inspecionar contratos/example.sema --drift none --json
@@ -162,6 +163,7 @@ gate.
 
 ## Core Commands
 
+- `sema sessao`: open a governed session; one envelope with workspace identity, artifact freshness, intent-specific blocking docs, gates, and next steps.
 - `sema iniciar`: create a governed starting point.
 - `sema validar`: validate `.sema` contracts.
 - `sema inspecionar`: inspect the applicable contract surface; add `--drift cache|fresh` to request code evidence.

package/package.json

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