@semacode/cli 0.9.0 → 1.0.0

package/docs/pagamento-ponta-a-ponta.md

@@ -0,0 +1,155 @@
+# Pagamento Ponta a Ponta na Sema
+
+Este documento descreve o vertical oficial de pagamento da Sema no fluxo publico atual.
+
+O objetivo nao e mostrar um exemplo fofo. O objetivo e demonstrar que a linguagem ja consegue modelar um fluxo de negocio real com:
+
+- contrato publico
+- regras
+- efeitos operacionais
+- transicoes de estado
+- orquestracao
+- erros publicos
+- testes executaveis
+
+## Arquivos de referencia
+
+- `exemplos/pagamento_dominio.sema`
+- `exemplos/pagamento.sema`
+
+## Como o vertical foi dividido
+
+### `exemplos.pagamento.dominio`
+
+Centraliza os contratos compartilhados:
+
+- `entity Pagamento`
+- `enum StatusPagamento`
+- `state ciclo_pagamento`
+
+### `exemplos.pagamento`
+
+Centraliza a operacao do vertical:
+
+- `task processar_pagamento`
+- `task confirmar_pagamento`
+- `task notificar_falha_pagamento`
+- `task registrar_timeout_pagamento`
+- `flow orquestracao_pagamento`
+- `route processar_pagamento_publico`
+
+## Narrativa do caso
+
+### Entrada publica
+
+A operacao entra por:
+
+- `route processar_pagamento_publico`
+
+Esse contrato publica:
+
+- `pagamento_id`
+- `valor`
+- `token`
+
+E expoe:
+
+- `pagamento`
+- `status`
+- erros publicos coerentes com a `task`
+
+### Task interna
+
+A `task processar_pagamento` faz o trabalho central:
+
+- valida entrada
+- consulta o gateway
+- persiste o pagamento
+- emite evento
+- notifica comprovante
+- registra auditoria
+- garante consistencia da saida
+
+### Estado e transicoes
+
+O `state ciclo_pagamento` ancora o contrato de transicao:
+
+- `PENDENTE -> AUTORIZADO`
+- `AUTORIZADO -> PROCESSADO`
+- `PENDENTE -> RECUSADO`
+
+A `task` explicita quais transicoes ela realmente usa.
+
+### Flow de orquestracao
+
+O `flow orquestracao_pagamento` demonstra:
+
+- passagem de contexto
+- confirmacao em caso de sucesso
+- notificacao em caso de recusa
+- registro de timeout em caso de indisponibilidade
+- ramificacao por erro tipado
+
+### Efeitos operacionais
+
+O vertical usa as 5 categorias oficiais da Sema:
+
+- `persistencia`
+- `consulta`
+- `evento`
+- `notificacao`
+- `auditoria`
+
+Tambem usa `criticidade` para deixar claro o peso operacional do efeito.
+
+### Falhas reais
+
+O vertical cobre explicitamente:
+
+- autorizacao negada
+- saldo insuficiente
+- timeout de gateway
+
+## Fluxo de trabalho recomendado
+
+### 1. Escrever ou ajustar os arquivos `.sema`
+
+Use o dominio compartilhado em um modulo e a operacao em outro modulo.
+
+### 2. Aplicar o formato canonico
+
+```bash
+sema formatar exemplos
+```
+
+### 3. Validar semanticamente
+
+```bash
+sema validar exemplos/pagamento.sema
+```
+
+### 4. Gerar codigo
+
+```bash
+sema compilar exemplos/pagamento.sema --alvo typescript --saida ./.tmp/pagamento-ts
+sema compilar exemplos/pagamento.sema --alvo python --saida ./.tmp/pagamento-py
+```
+
+### 5. Verificar o vertical completo
+
+```bash
+sema verificar exemplos/pagamento.sema --json --saida ./.tmp/verificacao-pagamento
+```
+
+## O que esse vertical prova
+
+Se esse vertical passa, a Sema ja consegue demonstrar que:
+
+- modela contrato publico
+- modela efeitos operacionais
+- modela falhas reais
+- modulariza dominio com `use`
+- gera artefatos coerentes para TypeScript e Python
+- executa testes gerados sem gambiarra conceitual
+
+Esse e o criterio pratico que sustenta o uso publico do vertical de pagamento como referencia para IA e geracao.

package/docs/prompt-base-ia-sema.md

@@ -2,7 +2,7 @@
 
 Este arquivo serve como prompt-base oficial para qualquer IA que precise ler, escrever, revisar ou transformar arquivos `.sema`.
 
-O objetivo nao e fazer a IA "improvisar bonito". O objetivo e fazer a IA operar a linguagem com previsibilidade.
+O objetivo nao e fazer a IA "improvisar bonito". O objetivo e fazer a IA operar a linguagem com previsibilidade. A Sema nao foi desenhada para ergonomia humana como prioridade; ela foi desenhada para IA.
 
 ## Prompt-base
 
@@ -11,7 +11,7 @@ Use o texto abaixo como base:
 ```text
 Voce esta trabalhando com Sema, um Protocolo de Governanca de Intencao para IA e backend vivo.
 
-Tecnicamente, a Sema funciona como linguagem de intencao orientada a contrato. Operacionalmente, ela existe para governar semantica acima da stack, nao para substituir arquitetura, design ou curadoria humana.
+Tecnicamente, a Sema funciona como linguagem de intencao orientada a contrato. Operacionalmente, ela existe para governar semantica acima da stack e reduzir ambiguidade para IA, nao para substituir arquitetura, design ou curadoria humana.
 
 Trate a Sema como linguagem de especificacao executavel e protocolo de governanca semantica. Nao invente sintaxe, palavras-chave ou blocos fora da gramatica e dos exemplos oficiais.
 
@@ -20,7 +20,8 @@ Fontes de verdade, em ordem:
 2. gramatica e documentacao de sintaxe da Sema
 3. especificacao semantica da linguagem
 4. exemplos oficiais, com prioridade para o vertical de pagamento
-5. AST, IR e diagnosticos exportados pela CLI em JSON
+5. `sema resumo` e `briefing.min.json` quando a IA for pequena
+6. AST, IR e diagnosticos exportados pela CLI em JSON quando a capacidade aguentar
 
 Regras de operacao:
 - preserve o significado semantico
@@ -57,6 +58,12 @@ Se voce quiser um prompt menor para uso frequente:
 Trabalhe com Sema como DSL semantica orientada a contrato. Nao invente sintaxe. Use os exemplos oficiais e a gramatica como referencia de escrita. Use `ir --json` como fonte de verdade semantica, `diagnosticos --json` como fonte de correcao e `sema formatar` como fonte unica de estilo. Antes de encerrar, rode validacao e verificacao.
 ```
 
+Se voce quiser um prompt ainda mais curto e pronto para colar, use:
+
+```bash
+sema prompt-curto caminho/arquivo.sema --curto --para mudanca
+```
+
 ## Variacao para revisao
 
 Use esta versao quando a IA for revisar `.sema` em vez de criar:

package/docs/sintaxe.md

@@ -0,0 +1,267 @@
+# 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`
+- `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`
+
+## 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`
+- `execucao` com `idempotencia`, `timeout`, `retry`, `compensacao` e `criticidade_operacional`
+- strings operacionais como `arquivo`, `timeout`, `retry` e `compensacao` 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
+- vinculo rastreavel
+- execucao explicita
+- superficie moderna de primeira classe

package/exemplos/automacao.sema

@@ -0,0 +1,107 @@
+module exemplos.automacao {
+  state onboarding_status {
+    origem: automacao
+    fields {
+      lead_id: Id
+      etapa_atual: Texto
+      concluido: Booleano
+    }
+  }
+
+  task executar_onboarding {
+    input {
+      lead_id: Id required
+      email: Email required
+    }
+    output {
+      protocolo: Id
+    }
+    rules {
+      lead_id deve_ser valido
+      email deve_ser email_valido
+    }
+    effects {
+      consulta crm
+      persistencia conta
+      notificacao email detalhe_boas_vindas
+      auditoria onboarding
+    }
+    guarantees {
+      protocolo existe
+      persistencia concluida
+    }
+    tests {
+      caso "onboarding completo" {
+        given {
+          lead_id: "lead_1"
+          email: "cliente@empresa.com"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task registrar_auditoria {
+    input {
+      protocolo: Id required
+    }
+    output {
+      auditoria_id: Id
+    }
+    effects {
+      auditoria onboarding
+    }
+    guarantees {
+      auditoria_id existe
+    }
+    tests {
+      caso "auditoria registrada" {
+        given {
+          protocolo: "prot_1"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task registrar_falha_onboarding {
+    input {
+      lead_id: Id required
+    }
+    output {
+      protocolo_falha: Id
+    }
+    effects {
+      auditoria falha_onboarding
+      persistencia onboarding_falha
+    }
+    guarantees {
+      protocolo_falha existe
+    }
+    tests {
+      caso "falha registrada" {
+        given {
+          lead_id: "lead_1"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  flow onboarding_cliente {
+    lead_id: Id
+    email: Email
+    etapa receber usa executar_onboarding com lead_id = lead_id, email = email quando (sucesso existe ou persistencia concluida) em_sucesso auditar em_erro registrar_falha
+    etapa auditar usa registrar_auditoria com protocolo = receber.protocolo depende_de receber
+    etapa registrar_falha usa registrar_falha_onboarding com lead_id = lead_id depende_de receber
+  }
+}

package/exemplos/cadastro_usuario.sema

@@ -0,0 +1,54 @@
+module exemplos.cadastro.usuario {
+  docs {
+    resumo: "Cadastro de usuario com entidade,validacoes e persistencia declarada."
+  }
+
+  entity Usuario {
+    fields {
+      id: Id
+      nome: Texto
+      email: Email
+      ativo: Booleano
+    }
+  }
+
+  task criar_usuario {
+    input {
+      nome: Texto required
+      email: Email required
+    }
+    output {
+      usuario: Usuario
+    }
+    rules {
+      nome deve_ser preenchido
+      email deve_ser email_valido
+      email deve_ser unico em Usuario.email
+    }
+    effects {
+      persistencia Usuario
+      evento usuario_criado
+      auditoria cadastro_usuario
+    }
+    guarantees {
+      usuario existe
+      persistencia concluida
+    }
+    error {
+      email_duplicado: "Ja existe usuario com este email."
+      entrada_invalida: "Os dados informados nao atendem as regras."
+    }
+    tests {
+      caso "cria usuario valido" {
+        given {
+          nome: "Ana"
+          email: "ana@empresa.com"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+}

package/exemplos/calculadora.sema

@@ -0,0 +1,78 @@
+module exemplos.calculadora {
+  docs {
+    resumo: "Operacoes aritmeticas simples com garantias e testes."
+  }
+
+  comments {
+    observacao: "Exemplo base para demonstrar tarefas semanticas puras."
+  }
+
+  task somar {
+    input {
+      a: Numero required
+      b: Numero required
+    }
+    output {
+      resultado: Numero
+    }
+    rules {
+      a deve_ser numero_valido
+      b deve_ser numero_valido
+    }
+    effects {
+      auditoria operacao soma
+    }
+    guarantees {
+      resultado existe
+    }
+    error {
+      entrada_invalida: "Os valores precisam ser numericos."
+    }
+    tests {
+      caso "soma basica" {
+        given {
+          a: 2
+          b: 3
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task dividir {
+    input {
+      dividendo: Numero required
+      divisor: Numero required
+    }
+    output {
+      resultado: Numero
+    }
+    rules {
+      divisor deve_ser diferente_de_zero
+    }
+    effects {
+      auditoria operacao divisao
+    }
+    guarantees {
+      resultado existe
+    }
+    error {
+      divisor_zero: "Nao e permitido dividir por zero."
+    }
+    tests {
+      caso "divisao valida" {
+        given {
+          dividendo: 10
+          divisor: 2
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+}