@semacode/cli 1.5.16 → 1.5.18

package/exemplos/permissao.sema

@@ -0,0 +1,121 @@
+module exemplos.permissao {
+  docs {
+    resumo: "Controle de acesso baseado em papeis e permissoes granulares."
+  }
+
+  entity Papel {
+    fields {
+      id: Id
+      nome: Texto
+      descricao: Texto
+    }
+  }
+
+  entity Permissao {
+    fields {
+      id: Id
+      recurso: Texto
+      acao: Texto
+      descricao: Texto
+    }
+  }
+
+  task atribuir_papel {
+    input {
+      usuario_id: Id required
+      papel_id: Id required
+    }
+    output {
+      atribuicao_id: Id
+    }
+    rules {
+      usuario_id deve_ser valido
+      papel_id deve_ser valido
+    }
+    effects {
+      consulta Usuario por usuario_id
+      consulta Papel por papel_id
+      persistencia AtribuicaoPapel
+      evento papel_atribuido criticidade = media
+      auditoria atribuicao_papel criticidade = alta
+    }
+    guarantees {
+      atribuicao_id existe
+    }
+    error {
+      usuario_nao_encontrado: "Usuario nao localizado."
+      papel_nao_encontrado: "Papel nao localizado."
+      atribuicao_duplicada: "Usuario ja possui este papel."
+    }
+    tests {
+      caso "atribui papel admin" {
+        given { usuario_id: "usr_1"  papel_id: "papel_admin" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+
+  task verificar_permissao {
+    input {
+      usuario_id: Id required
+      recurso: Texto required
+      acao: Texto required
+    }
+    output {
+      autorizado: Booleano
+    }
+    rules {
+      usuario_id deve_ser valido
+      recurso deve_ser preenchido
+      acao deve_ser preenchida
+    }
+    effects {
+      consulta AtribuicaoPapel por usuario_id
+      consulta PermissaoPapel por papel_id
+      auditoria verificacao_permissao
+    }
+    guarantees {
+      autorizado existe
+    }
+    tests {
+      caso "usuario autorizado" {
+        given { usuario_id: "usr_admin"  recurso: "relatorios"  acao: "exportar" }
+        expect { sucesso: verdadeiro }
+      }
+      caso "usuario sem permissao" {
+        given { usuario_id: "usr_basico"  recurso: "admin"  acao: "deletar" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+
+  task revogar_papel {
+    input {
+      usuario_id: Id required
+      papel_id: Id required
+      motivo: Texto required
+    }
+    output {
+      protocolo: Id
+    }
+    rules {
+      usuario_id deve_ser valido
+      papel_id deve_ser valido
+      motivo deve_ser preenchido
+    }
+    effects {
+      persistencia AtribuicaoPapel
+      evento papel_revogado criticidade = alta
+      auditoria revogacao_papel criticidade = alta
+    }
+    guarantees {
+      protocolo existe
+    }
+    tests {
+      caso "revoga papel" {
+        given { usuario_id: "usr_1"  papel_id: "papel_admin"  motivo: "Saida da equipe" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+}

package/exemplos/persistencia_vendor_first.sema

@@ -0,0 +1,86 @@
+module exemplos.persistencia.vendor_first {
+  database principal_postgres {
+    engine: postgres
+    schema: public
+    consistency: forte
+    durability: alta
+    transaction_model: mvcc
+    query_model: sql
+    capabilities {
+      joins
+      views
+    }
+    table pedidos {
+      entity: Pedido
+    }
+    relationship pedido_cliente {
+      from: Pedido
+      to: Cliente
+    }
+    query buscar_pedidos {
+      mode: sql
+    }
+  }
+
+  database principal_mysql {
+    engine: mysql
+    consistency: forte
+    durability: alta
+    transaction_model: bloqueio
+    query_model: sql
+    table faturamento {
+      table: faturamento
+    }
+    query buscar_faturas {
+      mode: sql
+    }
+  }
+
+  database principal_sqlite {
+    engine: sqlite
+    consistency: snapshot
+    durability: media
+    transaction_model: single_thread
+    query_model: sql
+    table cache_local {
+      table: cache_local
+    }
+    retention limpeza_local {
+      retention: 7d
+    }
+  }
+
+  database principal_mongodb {
+    engine: mongodb
+    consistency: eventual
+    durability: alta
+    transaction_model: documento
+    query_model: documento
+    collection pedidos {
+      collection: pedidos
+    }
+    document pedido_snapshot {
+      entity: PedidoSnapshot
+    }
+    query pipeline_pedido {
+      mode: pipeline
+    }
+  }
+
+  database principal_redis {
+    engine: redis
+    consistency: eventual
+    durability: media
+    transaction_model: single_thread
+    query_model: chave_valor
+    keyspace cache_pedidos {
+      ttl: 300s
+    }
+    stream eventos_pedido {
+      surface: fila
+    }
+    retention expurgo_cache {
+      retention: 300s
+    }
+  }
+}

package/exemplos/relatorio.sema

@@ -0,0 +1,93 @@
+module exemplos.relatorio {
+  docs {
+    resumo: "Geracao assincrona de relatorios com download e notificacao."
+  }
+
+  entity Relatorio {
+    fields {
+      id: Id
+      tipo: Texto
+      parametros: Objeto
+      status: Texto
+      url_download: Texto
+      solicitado_por: Id
+      criado_em: Timestamp
+      concluido_em: Timestamp
+    }
+  }
+
+  task solicitar_relatorio {
+    input {
+      tipo: Texto required
+      data_inicio: Data required
+      data_fim: Data required
+      formato: Texto
+    }
+    output {
+      relatorio_id: Id
+    }
+    rules {
+      tipo em [VENDAS, ESTOQUE, USUARIOS, FINANCEIRO]
+      data_inicio deve_ser anterior_a data_fim
+      formato em [PDF, CSV, XLSX]
+    }
+    effects {
+      persistencia Relatorio
+      evento relatorio_solicitado criticidade = baixa
+      auditoria solicitacao_relatorio
+    }
+    state ciclo_relatorio {
+      transitions {
+        PENDENTE -> EM_PROCESSAMENTO
+      }
+    }
+    guarantees {
+      relatorio_id existe
+    }
+    error {
+      tipo_invalido: "Tipo de relatorio nao suportado."
+      periodo_invalido: "Data de inicio deve ser anterior a data de fim."
+      limite_periodo: "Periodo maximo e de 12 meses."
+    }
+    tests {
+      caso "solicita relatorio de vendas" {
+        given { tipo: "VENDAS"  data_inicio: "2025-01-01"  data_fim: "2025-03-31"  formato: "PDF" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+
+  task concluir_relatorio {
+    input {
+      relatorio_id: Id required
+      url_download: Texto required
+    }
+    output {
+      protocolo: Id
+    }
+    rules {
+      relatorio_id deve_ser valido
+      url_download deve_ser preenchida
+    }
+    effects {
+      persistencia Relatorio
+      notificacao usuario relatorio_pronto criticidade = media
+      evento relatorio_concluido
+      auditoria conclusao_relatorio
+    }
+    state ciclo_relatorio {
+      transitions {
+        EM_PROCESSAMENTO -> CONCLUIDO
+      }
+    }
+    guarantees {
+      protocolo existe
+    }
+    tests {
+      caso "conclui relatorio" {
+        given { relatorio_id: "rel_1"  url_download: "https://storage/rel_1.pdf" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+}

package/exemplos/replica_analitica_erp.sema

@@ -0,0 +1,160 @@
+module exemplos.replica.analitica_erp {
+  docs {
+    resumo: "Exemplo publico neutro de replica analitica ERP para banco analytics: agente pode consultar a origem operacional em modo leitura e persistir apenas no destino analitico."
+  }
+
+  database erp_origem_mariadb {
+    engine: mysql
+    consistency: forte
+    durability: alta
+    transaction_model: bloqueio
+    query_model: sql
+    capabilities {
+      read_only
+      views
+    }
+    table vendas_operacionais {
+      entity: VendaOperacional
+    }
+    query extrair_vendas {
+      mode: sql
+    }
+  }
+
+  database analytics_postgres {
+    engine: postgres
+    schema: public
+    consistency: eventual
+    durability: alta
+    transaction_model: mvcc
+    query_model: sql
+    capabilities {
+      upsert
+      views
+    }
+    table vendas_analytics {
+      entity: VendaAnalitica
+    }
+    query carregar_vendas_analytics {
+      mode: sql
+    }
+  }
+
+  entity VendaOperacional {
+    fields {
+      id: Id
+      loja_id: Id
+      data_venda: Data
+      valor_total: Decimal
+      payload_origem: Objeto
+    }
+    invariants {
+      id existe
+      loja_id existe
+      data_venda existe
+      valor_total >= 0
+    }
+  }
+
+  entity VendaAnalitica {
+    fields {
+      id: Id
+      loja_id: Id
+      data_venda: Data
+      valor_total: Decimal
+      sincronizado_em: Timestamp
+    }
+    invariants {
+      id existe
+      loja_id existe
+      data_venda existe
+      valor_total >= 0
+      sincronizado_em existe
+    }
+  }
+
+  task sincronizar_vendas_erp_para_analytics {
+    input {
+      loja_id: Id required
+      periodo_inicio: Data required
+      periodo_fim: Data required
+    }
+    output {
+      registros_sincronizados: Inteiro
+      banco_producao_modificado: Booleano
+      sincronizado_em: Timestamp
+    }
+    authz {
+      escopo: analytics.replica.sincronizar
+      tenant: obrigatorio
+    }
+    dados {
+      classificacao_padrao: interno
+      redacao_log: obrigatoria
+      input {
+        loja_id: interno
+        periodo_inicio: interno
+        periodo_fim: interno
+      }
+      output {
+        registros_sincronizados: interno
+        banco_producao_modificado: interno
+        sincronizado_em: interno
+      }
+    }
+    audit {
+      evento: analytics.replica.erp_sincronizada
+      ator: sistema.analytics
+      correlacao: request_id
+      retencao: "180d"
+      motivo: obrigatorio
+    }
+    forbidden {
+      shell.exec
+      log.segredo
+      retorno.credencial
+    }
+    rules {
+      loja_id deve_ser valido
+      periodo_inicio deve_ser anterior_a periodo_fim
+    }
+    effects {
+      consulta erp_origem_mariadb criticidade = alta
+      persistencia analytics_postgres criticidade = media
+      auditoria sincronizacao_vendas criticidade = alta
+    }
+    vinculos {
+      recurso: erp_origem_mariadb
+      recurso: analytics_postgres
+      tabela: vendas_operacionais
+      tabela: vendas_analytics
+    }
+    execucao {
+      idempotencia: verdadeiro
+      timeout: "60s"
+      retry: "3x exponencial"
+      compensacao: "reexecutar_janela_analitica"
+      criticidade_operacional: alta
+    }
+    guarantees {
+      registros_sincronizados >= 0
+      banco_producao_modificado == falso
+      sincronizado_em existe
+    }
+    tests {
+      caso "sincroniza janela sem escrever na origem" {
+        given {
+          loja_id: "loja_001"
+          periodo_inicio: "2026-05-01"
+          periodo_fim: "2026-05-15"
+        }
+
+        expect {
+          sucesso: verdadeiro
+          registros_sincronizados: 42
+          banco_producao_modificado: falso
+        }
+      }
+    }
+  }
+}

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
+  }
+}