@semacode/cli 0.9.0 → 1.1.0

package/exemplos/pagamento.sema

@@ -0,0 +1,222 @@
+module exemplos.pagamento {
+  docs {
+    resumo: "Vertical oficial de pagamento da Sema 0.5,usado como referencia de utilidade real controlada."
+  }
+
+  use exemplos.pagamento.dominio
+
+  task processar_pagamento {
+    input {
+      pagamento_id: Id required
+      valor: Decimal required
+      token: Texto required
+    }
+    output {
+      pagamento: Pagamento
+      status: StatusPagamento
+    }
+    rules {
+      valor > 0
+      token existe
+      token deve_ser valido
+    }
+    effects {
+      consulta gateway_pagamento criticidade = alta
+      persistencia Pagamento criticidade = alta
+      evento pagamento_autorizado criticidade = media
+      notificacao cliente comprovante_pagamento criticidade = media
+      auditoria pagamento criticidade = alta
+    }
+    state ciclo_pagamento {
+      transitions {
+        PENDENTE -> AUTORIZADO
+        AUTORIZADO -> PROCESSADO
+      }
+    }
+    guarantees {
+      pagamento existe
+      status em [AUTORIZADO, PROCESSADO]
+      pagamento.status == status
+    }
+    error {
+      autorizacao_negada: "A operacao foi recusada pelo gateway."
+      saldo_insuficiente: "O saldo nao cobre o valor da cobranca."
+      timeout_gateway: "O gateway nao respondeu em tempo habil."
+    }
+    tests {
+      caso "pagamento autorizado" {
+        given {
+          pagamento_id: "pag_1"
+          valor: 199.9
+          token: "tok_ok"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+      caso "pagamento recusado por autorizacao" {
+        given {
+          pagamento_id: "pag_erro"
+          valor: 10
+          token: "tok_recusado"
+        }
+
+        expect {
+          sucesso: falso
+        }
+
+        error {
+          tipo: "autorizacao_negada"
+        }
+      }
+      caso "pagamento falha por timeout" {
+        given {
+          pagamento_id: "pag_timeout"
+          valor: 10
+          token: "tok_timeout"
+        }
+
+        expect {
+          sucesso: falso
+        }
+
+        error {
+          tipo: "timeout_gateway"
+        }
+      }
+    }
+  }
+
+  task confirmar_pagamento {
+    input {
+      pagamento_id: Id required
+    }
+    output {
+      status: StatusPagamento
+    }
+    rules {
+      pagamento_id existe
+    }
+    effects {
+      consulta gateway_pagamento criticidade = alta
+      persistencia Pagamento criticidade = alta
+      evento pagamento_confirmado criticidade = media
+      auditoria conciliacao_pagamento criticidade = alta
+    }
+    state ciclo_pagamento {
+      transitions {
+        AUTORIZADO -> PROCESSADO
+      }
+    }
+    guarantees {
+      status == PROCESSADO
+    }
+    tests {
+      caso "confirma pagamento autorizado" {
+        given {
+          pagamento_id: "pag_1"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task notificar_falha_pagamento {
+    input {
+      pagamento_id: Id required
+      motivo: Texto required
+    }
+    output {
+      protocolo_notificacao: Id
+    }
+    effects {
+      notificacao cliente falha_pagamento criticidade = alta
+      auditoria falha_pagamento criticidade = media
+    }
+    guarantees {
+      protocolo_notificacao existe
+    }
+    tests {
+      caso "notifica falha por recusa" {
+        given {
+          pagamento_id: "pag_erro"
+          motivo: "autorizacao_negada"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task registrar_timeout_pagamento {
+    input {
+      pagamento_id: Id required
+    }
+    output {
+      auditoria_id: Id
+    }
+    effects {
+      auditoria timeout_gateway criticidade = alta
+      persistencia incidente_pagamento criticidade = media
+    }
+    guarantees {
+      auditoria_id existe
+    }
+    tests {
+      caso "registra timeout" {
+        given {
+          pagamento_id: "pag_timeout"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  flow orquestracao_pagamento {
+    pagamento_id: Id
+    valor: Decimal
+    token: Texto
+    etapa autorizar usa processar_pagamento com pagamento_id = pagamento_id, valor = valor, token = token em_sucesso confirmar em_erro registrar_falha por_erro autorizacao_negada = notificar_falha, timeout_gateway = registrar_timeout
+    etapa confirmar usa confirmar_pagamento com pagamento_id = pagamento_id depende_de autorizar
+    etapa notificar_falha usa notificar_falha_pagamento com pagamento_id = pagamento_id, motivo = autorizacao_negada depende_de autorizar
+    etapa registrar_timeout usa registrar_timeout_pagamento com pagamento_id = pagamento_id depende_de autorizar
+    etapa registrar_falha usa registrar_timeout_pagamento com pagamento_id = pagamento_id depende_de autorizar
+    effects {
+      auditoria fluxo_pagamento criticidade = alta
+      evento pagamento_em_processamento criticidade = media
+    }
+  }
+
+  route processar_pagamento_publico {
+    metodo: POST
+    caminho: /pagamentos/processar
+    task: processar_pagamento
+    input {
+      pagamento_id: Id required
+      valor: Decimal required
+      token: Texto required
+    }
+    output {
+      pagamento: Pagamento required
+      status: StatusPagamento required
+    }
+    effects {
+      auditoria pagamento_publico criticidade = alta
+      evento pagamento_requisitado criticidade = media
+    }
+    error {
+      autorizacao_negada: "Erro publico quando o gateway recusa a operacao."
+      saldo_insuficiente: "Erro publico quando nao ha saldo suficiente."
+      timeout_gateway: "Erro publico quando o gateway nao responde."
+    }
+  }
+}

package/exemplos/pagamento_dominio.sema

@@ -0,0 +1,35 @@
+module exemplos.pagamento.dominio {
+  docs {
+    resumo: "Contratos de dominio compartilhados pelo vertical oficial de pagamento da Sema 0.5."
+  }
+
+  entity Pagamento {
+    fields {
+      id: Id
+      valor: Decimal
+      status: StatusPagamento
+    }
+  }
+
+  enum StatusPagamento {
+    PENDENTE,
+    AUTORIZADO,
+    RECUSADO,
+    PROCESSADO
+  }
+
+  state ciclo_pagamento {
+    fields {
+      status: StatusPagamento
+      conciliado: Booleano
+    }
+    invariants {
+      status existe
+    }
+    transitions {
+      PENDENTE -> AUTORIZADO
+      AUTORIZADO -> PROCESSADO
+      PENDENTE -> RECUSADO
+    }
+  }
+}

package/exemplos/testes_embutidos.sema

@@ -0,0 +1,45 @@
+module exemplos.testes.embutidos {
+  task validar_documento {
+    input {
+      documento: Texto required
+    }
+    output {
+      valido: Booleano
+      motivo: Texto
+    }
+    rules {
+      documento deve_ser preenchido
+    }
+    effects {
+      auditoria validacao_documento
+    }
+    guarantees {
+      valido existe
+      motivo existe
+    }
+    tests {
+      caso "documento valido" {
+        given {
+          documento: 12345678900
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+      caso "documento vazio" {
+        given {
+          documento: ""
+        }
+
+        expect {
+          sucesso: falso
+        }
+
+        error {
+          tipo: "entrada_invalida"
+        }
+      }
+    }
+  }
+}

package/exemplos/tratamento_erro.sema

@@ -0,0 +1,157 @@
+module exemplos.tratamento.erro {
+  task executar_operacao_sensivel {
+    input {
+      chave: Texto required
+    }
+    output {
+      protocolo: Id
+    }
+    rules {
+      chave existe e chave deve_ser preenchida
+    }
+    effects {
+      consulta cofre
+      auditoria falha_operacao_sensivel
+    }
+    guarantees {
+      protocolo existe
+    }
+    error {
+      acesso_negado: "A chave informada nao tem permissao."
+      recurso_indisponivel: "O servico esta temporariamente indisponivel."
+      auditoria_obrigatoria: "Toda falha precisa ser registrada."
+    }
+    tests {
+      caso "falha por acesso negado" {
+        given {
+          chave: "sem_permissao"
+        }
+
+        expect {
+          sucesso: falso
+        }
+
+        error {
+          tipo: "acesso_negado"
+        }
+      }
+    }
+  }
+
+  task responder_acesso_negado {
+    input {
+      chave: Texto required
+    }
+    output {
+      protocolo_resposta: Id
+    }
+    effects {
+      notificacao cliente acesso_negado
+      auditoria acesso_negado
+    }
+    guarantees {
+      protocolo_resposta existe
+    }
+    tests {
+      caso "responde acesso negado" {
+        given {
+          chave: "sem_permissao"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task responder_retentativa {
+    input {
+      chave: Texto required
+    }
+    output {
+      protocolo_resposta: Id
+    }
+    effects {
+      notificacao cliente retentativa_programada
+      auditoria retentativa
+    }
+    guarantees {
+      protocolo_resposta existe
+    }
+    tests {
+      caso "agenda retentativa" {
+        given {
+          chave: "instavel"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task registrar_auditoria_falha {
+    input {
+      chave: Texto required
+    }
+    output {
+      auditoria_id: Id
+    }
+    effects {
+      auditoria falha_operacional
+      persistencia auditoria_falha
+    }
+    guarantees {
+      auditoria_id existe
+    }
+    tests {
+      caso "audita falha" {
+        given {
+          chave: "sem_permissao"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task registrar_sucesso {
+    input {
+      protocolo: Id required
+    }
+    output {
+      registro_id: Id
+    }
+    effects {
+      auditoria operacao_concluida
+      evento operacao_sensivel_concluida
+    }
+    guarantees {
+      registro_id existe
+    }
+    tests {
+      caso "registra sucesso" {
+        given {
+          protocolo: "prot_1"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  flow resposta_segura {
+    chave: Texto
+    etapa tentar usa executar_operacao_sensivel com chave = chave em_sucesso concluir em_erro registrar_falha por_erro acesso_negado = tratar_acesso_negado, recurso_indisponivel = agendar_retentativa
+    etapa tratar_acesso_negado usa responder_acesso_negado com chave = chave depende_de tentar
+    etapa agendar_retentativa usa responder_retentativa com chave = chave depende_de tentar
+    etapa registrar_falha usa registrar_auditoria_falha com chave = chave depende_de tentar
+    etapa concluir usa registrar_sucesso com protocolo = tentar.protocolo depende_de tentar
+  }
+}

package/llms-full.txt

@@ -0,0 +1,34 @@
+Sema is an AI-first semantic language and tooling stack for explicit software intent, drift analysis, and safer intervention in live backend systems.
+
+This repository is not optimized for human-first reading. It is optimized for AI agents that need compressed, canonical semantic context.
+
+Canonical entrypoints in the repository root:
+1. `llms.txt`
+2. `SEMA_BRIEF.md`
+3. `SEMA_INDEX.json`
+4. `AGENTS.md`
+5. `README.md`
+6. `docs/AGENT_STARTER.md`
+
+Capacity routing:
+- small/free AI: `llms.txt` -> `SEMA_BRIEF.micro.txt` -> `SEMA_INDEX.json` -> `AGENTS.md`
+- medium AI: `llms.txt` -> `SEMA_BRIEF.curto.txt` -> `SEMA_INDEX.json` -> `AGENTS.md` -> `README.md`
+- large/tool-using AI: `llms-full.txt` -> `SEMA_BRIEF.md` -> `SEMA_INDEX.json` -> `AGENTS.md` -> `README.md`
+
+Source-of-truth order:
+1. root Sema artifacts
+2. CLI JSON outputs
+3. official docs
+4. official examples
+5. raw implementation code
+
+Useful commands:
+- `sema resumo <arquivo-ou-pasta> --micro --para mudanca`
+- `sema prompt-curto <arquivo-ou-pasta> --curto --para review`
+- `sema drift <arquivo-ou-pasta> --json`
+- `sema contexto-ia <arquivo.sema> --saida ./.tmp/contexto --json`
+- `sema validar <arquivo-ou-pasta> --json`
+- `sema verificar <arquivo-ou-pasta> --json`
+
+Do not ask the model to infer semantics that are already available in Sema artifacts.
+Do not start from raw source code if `SEMA_BRIEF`, `SEMA_INDEX`, `drift`, or `briefing` are available.

package/llms.txt

@@ -0,0 +1,17 @@
+Sema is an AI-first semantic language and tooling stack for backend intent.
+
+This repository is not human-first. Use the canonical AI entrypoints before raw code.
+
+Read in this order:
+1. SEMA_BRIEF.micro.txt or SEMA_BRIEF.md
+2. SEMA_INDEX.json
+3. AGENTS.md
+4. README.md
+
+Capacity routing:
+- small models: llms.txt -> SEMA_BRIEF.micro.txt -> SEMA_INDEX.json
+- medium models: llms.txt -> SEMA_BRIEF.curto.txt -> SEMA_INDEX.json -> README.md
+- large models: llms-full.txt -> SEMA_BRIEF.md -> SEMA_INDEX.json -> README.md
+
+Prefer Sema artifacts over raw source code when both exist.
+Prefer `drift`, `briefing`, `ir`, and `diagnosticos` over guesswork.

package/node_modules/@sema/gerador-dart/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/gerador-dart",
-  "version": "0.9.0",
+  "version": "1.1.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/node_modules/@sema/gerador-python/dist/index.js

@@ -1,15 +1,84 @@
 import path from "node:path";
 import { descreverEstruturaModulo, mapearTipoParaPython, normalizarNomeModulo, normalizarNomeParaSimbolo, } from "@sema/padroes";
 const TIPOS_PRIMITIVOS_SEMA = new Set(["Texto", "Numero", "Inteiro", "Decimal", "Booleano", "Data", "DataHora", "Id", "Email", "Url", "Json", "Vazio"]);
+function dividirTipoNoNivelRaiz(valor, separador) {
+    const partes = [];
+    let atual = "";
+    let profundidade = 0;
+    for (const caractere of valor) {
+        if (caractere === "<") {
+            profundidade += 1;
+            atual += caractere;
+            continue;
+        }
+        if (caractere === ">") {
+            profundidade = Math.max(0, profundidade - 1);
+            atual += caractere;
+            continue;
+        }
+        if (caractere === separador && profundidade === 0) {
+            if (atual.trim()) {
+                partes.push(atual.trim());
+            }
+            atual = "";
+            continue;
+        }
+        atual += caractere;
+    }
+    if (atual.trim()) {
+        partes.push(atual.trim());
+    }
+    return partes;
+}
+function coletarFolhasTipoPython(tipo) {
+    const limpo = tipo.trim();
+    if (!limpo) {
+        return [];
+    }
+    if (/^Opcional<.+>$/.test(limpo)) {
+        return coletarFolhasTipoPython(limpo.slice("Opcional<".length, -1));
+    }
+    const uniao = dividirTipoNoNivelRaiz(limpo, "|");
+    if (uniao.length > 1) {
+        return uniao.flatMap((item) => coletarFolhasTipoPython(item));
+    }
+    if (/^Lista<.+>$/.test(limpo)) {
+        return coletarFolhasTipoPython(limpo.slice("Lista<".length, -1));
+    }
+    if (/^Mapa<.+>$/.test(limpo)) {
+        return dividirTipoNoNivelRaiz(limpo.slice("Mapa<".length, -1), ",")
+            .flatMap((item) => coletarFolhasTipoPython(item));
+    }
+    return [limpo];
+}
+function mapearCampoParaPython(campo) {
+    let anotacao;
+    if (campo.cardinalidade === "lista") {
+        anotacao = `list[${mapearTipoParaPython(campo.tipoItem ?? campo.tipoBase)}]`;
+    }
+    else if (campo.cardinalidade === "mapa") {
+        anotacao = `dict[${mapearTipoParaPython(campo.chaveMapa ?? "Texto")}, ${mapearTipoParaPython(campo.valorMapa ?? "Json")}]`;
+    }
+    else if (campo.cardinalidade === "uniao") {
+        anotacao = campo.tiposAlternativos.map((tipo) => mapearTipoParaPython(tipo)).join(" | ");
+    }
+    else {
+        anotacao = mapearTipoParaPython(campo.tipoBase);
+    }
+    if (campo.opcional && !/\bNone\b/.test(anotacao)) {
+        return `${anotacao} | None`;
+    }
+    return anotacao;
+}
 function gerarDataclass(nome, campos) {
     const linhas = campos.length === 0
         ? "    pass"
         : campos.map((campo) => {
-            const tipoBase = mapearTipoParaPython(campo.tipo);
+            const tipoBase = mapearCampoParaPython(campo);
             if (campo.modificadores.includes("required")) {
                 return `    ${campo.nome}: ${tipoBase}`;
             }
-            return `    ${campo.nome}: ${tipoBase} | None = None`;
+            return `    ${campo.nome}: ${/\bNone\b/.test(tipoBase) ? tipoBase : `${tipoBase} | None`} = None`;
         }).join("\n");
     return `@dataclass\nclass ${nome}:\n${linhas}\n`;
 }
@@ -39,8 +108,10 @@ function coletarTiposExternos(modulo) {
         ...modulo.states.flatMap((state) => state.campos),
     ];
     for (const campo of campos) {
-        if (!TIPOS_PRIMITIVOS_SEMA.has(campo.tipo) && !locais.has(campo.tipo)) {
-            referenciados.add(campo.tipo);
+        for (const tipo of coletarFolhasTipoPython(campo.tipo)) {
+            if (!TIPOS_PRIMITIVOS_SEMA.has(tipo) && !locais.has(tipo)) {
+                referenciados.add(tipo);
+            }
         }
     }
     return [...referenciados].sort((a, b) => a.localeCompare(b, "pt-BR"));
@@ -87,7 +158,18 @@ function resolverExpressaoPython(expressao, camposConhecidos, variavel) {
             return `(not ${resolverExpressaoPython(expressao.termo, camposConhecidos, variavel)})`;
     }
 }
-function valorPadraoPython(tipo, nomeCampo) {
+function valorPadraoPython(campo) {
+    const tipo = campo.tipoBase;
+    const nomeCampo = campo.nome;
+    if (campo.cardinalidade === "lista") {
+        return "[]";
+    }
+    if (campo.cardinalidade === "mapa") {
+        return "{}";
+    }
+    if (campo.opcional) {
+        return "None";
+    }
     switch (tipo) {
         case "Texto":
         case "Id":
@@ -175,7 +257,7 @@ function paraPascalCase(valor) {
 }
 function gerarPreparacaoSaida(task) {
     const camposSaida = new Set(task.output.map((campo) => campo.nome));
-    const argumentos = task.output.map((campo) => `${campo.nome}=${valorPadraoPython(campo.tipo, campo.nome)}`).join(", ");
+    const argumentos = task.output.map((campo) => `${campo.nome}=${valorPadraoPython(campo)}`).join(", ");
     const ajustes = [];
     for (const garantia of task.garantiasEstruturadas) {
         if (garantia.tipo === "pertencimento" && garantia.valores && camposSaida.has(garantia.alvo)) {
@@ -426,18 +508,18 @@ function gerarFastApiSchemas(modulo, caminhoContrato) {
     ];
     for (const task of modulo.tasks) {
         linhas.push(`class ${task.nome}EntradaSchema(BaseModel):
-${task.input.length === 0 ? "    pass" : task.input.map((campo) => `    ${campo.nome}: ${mapearTipoParaPython(campo.tipo)}`).join("\n")}
+${task.input.length === 0 ? "    pass" : task.input.map((campo) => `    ${campo.nome}: ${mapearCampoParaPython(campo)}`).join("\n")}
 `);
         linhas.push(`class ${task.nome}SaidaSchema(BaseModel):
-${task.output.length === 0 ? "    pass" : task.output.map((campo) => `    ${campo.nome}: ${mapearTipoParaPython(campo.tipo)}`).join("\n")}
+${task.output.length === 0 ? "    pass" : task.output.map((campo) => `    ${campo.nome}: ${mapearCampoParaPython(campo)}`).join("\n")}
 `);
     }
     for (const route of modulo.routes) {
         linhas.push(`class ${route.nome}EntradaPublicaSchema(BaseModel):
-${route.inputPublico.length === 0 ? "    pass" : route.inputPublico.map((campo) => `    ${campo.nome}: ${mapearTipoParaPython(campo.tipo)}`).join("\n")}
+${route.inputPublico.length === 0 ? "    pass" : route.inputPublico.map((campo) => `    ${campo.nome}: ${mapearCampoParaPython(campo)}`).join("\n")}
 `);
         linhas.push(`class ${route.nome}SaidaPublicaSchema(BaseModel):
-${route.outputPublico.length === 0 ? "    pass" : route.outputPublico.map((campo) => `    ${campo.nome}: ${mapearTipoParaPython(campo.tipo)}`).join("\n")}
+${route.outputPublico.length === 0 ? "    pass" : route.outputPublico.map((campo) => `    ${campo.nome}: ${mapearCampoParaPython(campo)}`).join("\n")}
 `);
     }
     return linhas.join("\n");