@semacode/cli 1.3.2 → 1.3.6

package/docs/sintaxe.md

@@ -1,361 +0,0 @@
-# Sintaxe Canonica
-
-A Sema usa blocos declarativos com chaves e forma previsivel. A regra aqui nao e "ficar bonitinho para humano"; e reduzir ambiguidade para parser, IR, drift e contexto de IA.
-
-## Regras basicas
-
-- um arquivo `.sema` contem um `module` principal
-- cada bloco abre com palavra-chave e fecha com `}`
-- campos usam `nome: valor`
-- linhas declarativas continuam validas para regra, efeito, garantia, transicao e etapa de flow
-- `tests` contem blocos `caso`
-- quando uma palavra reservada aparece seguida de `:`, ela continua sendo campo, nao bloco
-
-## Blocos de primeira classe
-
-- `module`
-- `use`
-- `type`
-- `entity`
-- `enum`
-- `state`
-- `task`
-- `flow`
-- `route`
-- `worker`
-- `evento`
-- `fila`
-- `cron`
-- `webhook`
-- `cache`
-- `storage`
-- `policy`
-- `tests`
-- `docs`
-- `comments`
-
-## Subblocos mais usados
-
-- `input`
-- `output`
-- `rules`
-- `effects`
-- `auth`
-- `authz`
-- `dados`
-- `audit`
-- `segredos`
-- `forbidden`
-- `impl`
-- `vinculos`
-- `execucao`
-- `guarantees`
-- `error`
-- `fields`
-- `invariants`
-- `transitions`
-- `given`
-- `when`
-- `expect`
-
-## Tipos compostos
-
-A Sema agora aceita formas canonicas para payload mais denso sem empurrar tudo para `Json`.
-
-```sema
-input {
-  ids: Lista<Id> required
-  metadata: Mapa<Texto, Texto>
-  responsavel: Opcional<Usuario>
-  chave_publica: Texto|Id
-}
-```
-
-Formas suportadas:
-
-- `Lista<T>`
-- `Mapa<K, V>`
-- `Opcional<T>`
-- `T1|T2`
-- `T?`
-
-## Task com contrato operacional
-
-```sema
-task processar_pedido {
-  input {
-    pedido_id: Id required
-    itens: Lista<Texto> required
-  }
-  output {
-    protocolo: Id
-    status: Texto
-  }
-  impl {
-    ts: app.pedidos.processar
-  }
-  vinculos {
-    arquivo: "src/pedidos/processar.ts"
-    simbolo: app.pedidos.processar
-    fila: pedidos_processamento
-  }
-  execucao {
-    idempotencia: verdadeiro
-    timeout: "30s"
-    retry: "3x exponencial"
-    compensacao: "reverter_reserva"
-    criticidade_operacional: alta
-  }
-  effects {
-    persistencia pedidos criticidade = alta
-    auditoria pedidos criticidade = media
-  }
-  guarantees {
-    protocolo existe
-    status existe
-  }
-  error {
-    pedido_invalido {
-      mensagem: "payload invalido"
-      categoria: dominio
-      recuperabilidade: permanente
-      acao_chamador: corrigir_input
-      impacta_estado: falso
-      requer_compensacao: falso
-    }
-  }
-  tests {
-    caso "processa pedido valido" {
-      given {
-        pedido_id: "ped_1"
-      }
-      expect {
-        sucesso: verdadeiro
-      }
-    }
-  }
-}
-```
-
-## `impl`
-
-`impl` liga a task ou a superficie ao simbolo real do runtime.
-
-```sema
-impl {
-  ts: app.pedidos.processar
-  py: services.orders.processar
-  cs: Pedidos.Api.Controllers.PedidosController.Processar
-}
-```
-
-Regras:
-
-- cada origem aparece no maximo uma vez por bloco
-- o caminho aponta para simbolo, nao para chamada com `()`
-- `ts|typescript`, `py|python`, `dart`, `cs|csharp|dotnet`, `java`, `go|golang`, `rust|rs`, `cpp|cxx|cc|c++` sao origens validas
-
-## `vinculos`
-
-`vinculos` nao substitui `impl`. Ele complementa o contrato com rastros operacionais que ajudam IA e drift a mapear o sistema vivo.
-
-Campos comuns:
-
-- `arquivo`
-- `simbolo`
-- `rota`
-- `superficie`
-- `recurso`
-- `tabela`
-- `fila`
-- `worker`
-- `evento`
-- `cron`
-- `webhook`
-- `cache`
-- `storage`
-- `policy`
-
-Exemplo:
-
-```sema
-vinculos {
-  arquivo: "pacotes/cli/src/index.ts"
-  simbolo: cli.src.index.gerarContextoIa
-  webhook: "/interno/contexto-ia"
-}
-```
-
-## `execucao`
-
-`execucao` explicita comportamento operacional em vez de deixar isso espalhado pelo codigo ou pela cabeca da IA.
-
-```sema
-execucao {
-  idempotencia: verdadeiro
-  timeout: "15s"
-  retry: "fila"
-  compensacao: "nenhuma"
-  criticidade_operacional: media
-}
-```
-
-Campos canonicos:
-
-- `idempotencia`
-- `timeout`
-- `retry`
-- `compensacao`
-- `criticidade_operacional`
-
-## Seguranca semantica
-
-Em `task`, `route` e superficies modernas, a Sema agora aceita contratos de seguranca explicitos para reduzir adivinhacao em producao.
-
-- `auth`: como a chamada autentica, com `modo`, `estrategia`, `principal` e `origem`
-- `authz`: quem pode executar, com `papel`, `escopo`, `politica` e `tenant`
-- `dados`: classificacao de input/output, `redacao_log` e `retencao`
-- `audit`: trilha obrigatoria com `evento`, `ator`, `correlacao`, `retencao` e `motivo`
-- `segredos`: origem, escopo, rotacao e protecoes de segredo
-- `forbidden`: proibicoes explicitas como `shell.exec`, `network.egress`, `log.segredo` e `retorno.credencial`
-
-Exemplo:
-
-```sema
-task processar_pagamento {
-  input {
-    cliente_id: Id required
-    token_gateway: Texto required
-  }
-  output {
-    protocolo: Id
-    status: Texto
-  }
-  effects {
-    db.write Pagamento criticidade=alta privilegio=escrita isolamento=tenant
-    secret.read gateway_api_key criticidade=media privilegio=leitura isolamento=processo
-  }
-  auth {
-    modo: interno
-    estrategia: jwt
-    principal: servico
-    origem: worker
-  }
-  authz {
-    papel: pagamentos_admin
-    escopo: pagamentos.processar
-    tenant: isolado
-  }
-  dados {
-    classificacao_padrao: interno
-    redacao_log: obrigatoria
-    retencao: "90d"
-    input {
-      cliente_id: pii
-      token_gateway: credencial
-    }
-    output {
-      protocolo: interno
-      status: interno
-    }
-  }
-  audit {
-    evento: pagamentos.processado
-    ator: auth.servico
-    correlacao: request_id
-    retencao: "180d"
-    motivo: obrigatorio
-  }
-  segredos {
-    gateway_api_key {
-      origem: vault
-      escopo: runtime
-      acesso: gateway_pagamento
-      rotacao: "30d"
-      nao_logar: verdadeiro
-      nao_retornar: verdadeiro
-      mascarar: verdadeiro
-    }
-  }
-  forbidden {
-    shell.exec
-    retorno.credencial
-    log.segredo
-  }
-  guarantees {
-    protocolo existe
-    status existe
-  }
-}
-```
-
-Esses blocos nao tentam implementar seguranca magica. Eles tornam a intencao auditavel por parser, IR, `drift`, `contexto-ia` e verificacao semantica.
-
-## Superficies modernas
-
-A Sema nao fica presa em HTTP. As bordas abaixo sao blocos irmaos de `route`, com shape minimo compativel com `task`, `impl`, `vinculos`, `execucao` e `effects`.
-
-```sema
-worker preparar_briefing {
-  task: medir_drift
-  vinculos {
-    arquivo: "pacotes/cli/src/index.ts"
-    worker: contexto_ia
-  }
-  execucao {
-    retry: "fila_contexto"
-    criticidade_operacional: alta
-  }
-}
-
-webhook confirmar_contexto {
-  task: mapear_projeto
-  vinculos {
-    webhook: "/interno/contexto-ia"
-  }
-  execucao {
-    timeout: "15s"
-    criticidade_operacional: media
-  }
-}
-```
-
-## Flow com dependencia explicita
-
-```sema
-flow operar_contexto_ia {
-  entrada: Texto
-  etapa mapear usa mapear_projeto com entrada = entrada
-  etapa drift usa medir_drift com contrato = entrada depende_de mapear
-  etapa briefing usa preparar_briefing com entrada = entrada depende_de drift
-  effects {
-    auditoria contexto_ia criticidade = alta
-  }
-  vinculos {
-    simbolo: cli.src.index.comandoContextoIa
-  }
-}
-```
-
-## Forma canonica
-
-O formatador passa a preferir:
-
-- `vinculos` com `arquivo` antes de `simbolo`
-- `auth` com `modo`, `estrategia`, `principal` e `origem`
-- `authz` com `papel|papeis`, `escopo|escopos`, `politica` e `tenant`
-- `dados` com `classificacao_padrao`, `redacao_log` e `retencao`
-- `audit` com `evento`, `ator`, `correlacao`, `retencao` e `motivo`
-- `execucao` com `idempotencia`, `timeout`, `retry`, `compensacao` e `criticidade_operacional`
-- strings operacionais como `arquivo`, `timeout`, `retry`, `compensacao`, `retencao` e `rotacao` com aspas
-- tipos compostos sem espacos quebrados em `Lista<T>` e `Mapa<K, V>`
-
-## Resumo pratico
-
-Se a duvida for "isso vai ajudar a IA a editar com menos chute?", a sintaxe nova aponta para quatro coisas:
-
-- contrato rico
-- seguranca semantica explicita
-- vinculo rastreavel
-- execucao explicita
-- superficie moderna de primeira classe

package/exemplos/agendamento.sema

@@ -1,106 +0,0 @@
-module exemplos.agendamento {
-  docs {
-    resumo: "Agendamento de tarefas recorrentes e unicas com controle de execucao."
-  }
-
-  entity Agendamento {
-    fields {
-      id: Id
-      nome: Texto
-      tipo: Texto
-      expressao_cron: Texto
-      payload: Objeto
-      ativo: Booleano
-      ultima_execucao: Timestamp
-      proxima_execucao: Timestamp
-    }
-  }
-
-  entity ExecucaoAgendamento {
-    fields {
-      id: Id
-      agendamento_id: Id
-      status: Texto
-      iniciado_em: Timestamp
-      concluido_em: Timestamp
-      erro: Texto
-    }
-  }
-
-  task criar_agendamento {
-    input {
-      nome: Texto required
-      tipo: Texto required
-      expressao_cron: Texto required
-      payload: Objeto
-    }
-    output {
-      agendamento: Agendamento
-    }
-    rules {
-      nome deve_ser preenchido
-      expressao_cron deve_ser valida
-      tipo deve_ser registrado
-    }
-    effects {
-      persistencia Agendamento
-      evento agendamento_criado criticidade = baixa
-      auditoria criacao_agendamento
-    }
-    guarantees {
-      agendamento existe
-      agendamento.ativo == verdadeiro
-    }
-    error {
-      cron_invalido: "Expressao cron invalida."
-      tipo_nao_registrado: "Tipo de agendamento nao existe."
-      nome_duplicado: "Ja existe agendamento com este nome."
-    }
-    tests {
-      caso "cria agendamento diario" {
-        given { nome: "relatorio_diario"  tipo: "gerar_relatorio"  expressao_cron: "0 8 * * *" }
-        expect { sucesso: verdadeiro }
-      }
-    }
-  }
-
-  task executar_agendamento {
-    input {
-      agendamento_id: Id required
-    }
-    output {
-      execucao_id: Id
-    }
-    rules {
-      agendamento_id deve_ser valido
-      agendamento.ativo == verdadeiro
-    }
-    effects {
-      consulta Agendamento por agendamento_id
-      persistencia ExecucaoAgendamento
-      persistencia Agendamento
-      evento agendamento_executado criticidade = baixa
-      auditoria execucao_agendamento
-    }
-    state ciclo_execucao {
-      transitions {
-        PENDENTE -> EM_EXECUCAO
-        EM_EXECUCAO -> CONCLUIDO
-        EM_EXECUCAO -> FALHOU
-      }
-    }
-    guarantees {
-      execucao_id existe
-    }
-    error {
-      agendamento_inativo: "Agendamento esta desativado."
-      execucao_em_andamento: "Ja existe uma execucao em andamento para este agendamento."
-    }
-    tests {
-      caso "executa agendamento ativo" {
-        given { agendamento_id: "agd_1" }
-        expect { sucesso: verdadeiro }
-      }
-    }
-  }
-}

package/exemplos/assinatura.sema

@@ -1,136 +0,0 @@
-module exemplos.assinatura {
-  docs {
-    resumo: "Gestao de assinaturas recorrentes com upgrade, downgrade e cancelamento."
-  }
-
-  entity Assinatura {
-    fields {
-      id: Id
-      cliente_id: Id
-      plano_id: Id
-      status: Texto
-      inicio_em: Timestamp
-      proximo_vencimento: Timestamp
-      cancelada_em: Timestamp
-    }
-  }
-
-  task criar_assinatura {
-    input {
-      cliente_id: Id required
-      plano_id: Id required
-      token_pagamento: Texto required
-    }
-    output {
-      assinatura: Assinatura
-    }
-    rules {
-      cliente_id deve_ser valido
-      plano_id deve_ser valido
-      token_pagamento deve_ser valido
-    }
-    effects {
-      consulta Cliente por cliente_id
-      consulta Plano por plano_id
-      consulta gateway_pagamento criticidade = alta
-      persistencia Assinatura
-      evento assinatura_criada criticidade = alta
-      notificacao cliente confirmacao_assinatura criticidade = media
-      auditoria criacao_assinatura criticidade = alta
-    }
-    state ciclo_assinatura {
-      transitions {
-        PENDENTE -> ATIVA
-      }
-    }
-    guarantees {
-      assinatura existe
-      assinatura.status == ATIVA
-    }
-    error {
-      pagamento_recusado: "Pagamento inicial recusado."
-      cliente_ja_assina: "Cliente ja possui assinatura ativa."
-      plano_invalido: "Plano nao disponivel para assinatura."
-    }
-    tests {
-      caso "cria assinatura pro" {
-        given { cliente_id: "cli_1"  plano_id: "plano_pro"  token_pagamento: "tok_ok" }
-        expect { sucesso: verdadeiro }
-      }
-    }
-  }
-
-  task cancelar_assinatura {
-    input {
-      assinatura_id: Id required
-      motivo: Texto required
-      imediato: Booleano
-    }
-    output {
-      protocolo: Id
-    }
-    rules {
-      assinatura_id deve_ser valido
-      assinatura.status == ATIVA
-      motivo deve_ser preenchido
-    }
-    effects {
-      persistencia Assinatura
-      consulta gateway_pagamento criticidade = alta
-      evento assinatura_cancelada criticidade = alta
-      notificacao cliente confirmacao_cancelamento criticidade = media
-      auditoria cancelamento_assinatura criticidade = alta
-    }
-    state ciclo_assinatura {
-      transitions {
-        ATIVA -> CANCELADA
-        ATIVA -> PENDENTE_CANCELAMENTO
-      }
-    }
-    guarantees {
-      protocolo existe
-    }
-    error {
-      assinatura_ja_cancelada: "Assinatura ja foi cancelada."
-    }
-    tests {
-      caso "cancela assinatura ativa" {
-        given { assinatura_id: "asn_1"  motivo: "Nao preciso mais"  imediato: falso }
-        expect { sucesso: verdadeiro }
-      }
-    }
-  }
-
-  task renovar_assinatura {
-    input {
-      assinatura_id: Id required
-    }
-    output {
-      protocolo_cobranca: Id
-    }
-    rules {
-      assinatura_id deve_ser valido
-      assinatura.status == ATIVA
-      assinatura.proximo_vencimento <= hoje
-    }
-    effects {
-      consulta gateway_pagamento criticidade = alta
-      persistencia Assinatura
-      evento assinatura_renovada criticidade = media
-      auditoria renovacao_assinatura criticidade = alta
-    }
-    guarantees {
-      protocolo_cobranca existe
-    }
-    error {
-      pagamento_recusado: "Cobranca de renovacao recusada — assinatura sera suspensa."
-      assinatura_cancelada: "Nao e possivel renovar assinatura cancelada."
-    }
-    tests {
-      caso "renova assinatura no vencimento" {
-        given { assinatura_id: "asn_1" }
-        expect { sucesso: verdadeiro }
-      }
-    }
-  }
-}

package/exemplos/auditoria.sema

@@ -1,88 +0,0 @@
-module exemplos.auditoria {
-  docs {
-    resumo: "Registro imutavel de acoes criticas com rastreabilidade completa."
-  }
-
-  entity RegistroAuditoria {
-    fields {
-      id: Id
-      ator_id: Id
-      ator_tipo: Texto
-      acao: Texto
-      recurso: Texto
-      recurso_id: Id
-      dados_antes: Objeto
-      dados_depois: Objeto
-      ip_origem: Texto
-      timestamp: Timestamp
-      contexto: Objeto
-    }
-  }
-
-  task registrar_acao {
-    input {
-      ator_id: Id required
-      acao: Texto required
-      recurso: Texto required
-      recurso_id: Id required
-      dados_antes: Objeto
-      dados_depois: Objeto
-      ip_origem: Texto
-    }
-    output {
-      auditoria_id: Id
-    }
-    rules {
-      acao deve_ser preenchida
-      recurso deve_ser preenchido
-      ator_id deve_ser valido
-    }
-    effects {
-      persistencia RegistroAuditoria criticidade = alta
-    }
-    guarantees {
-      auditoria_id existe
-      RegistroAuditoria.imutavel == verdadeiro
-    }
-    error {
-      falha_persistencia: "Nao foi possivel registrar a auditoria — operacao bloqueada."
-    }
-    tests {
-      caso "registra acao critica" {
-        given { ator_id: "usr_1"  acao: "deletar_usuario"  recurso: "Usuario"  recurso_id: "usr_2" }
-        expect { sucesso: verdadeiro }
-      }
-    }
-  }
-
-  task consultar_historico {
-    input {
-      recurso: Texto required
-      recurso_id: Id required
-      data_inicio: Data
-      data_fim: Data
-    }
-    output {
-      registros: Lista
-      total: Inteiro
-    }
-    rules {
-      recurso deve_ser preenchido
-      recurso_id deve_ser valido
-    }
-    effects {
-      consulta RegistroAuditoria por recurso e recurso_id
-      auditoria consulta_historico
-    }
-    guarantees {
-      registros existe
-      total >= 0
-    }
-    tests {
-      caso "consulta historico de usuario" {
-        given { recurso: "Usuario"  recurso_id: "usr_1" }
-        expect { sucesso: verdadeiro }
-      }
-    }
-  }
-}