@semacode/cli 1.2.17 → 1.3.0

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

@@ -1,155 +0,0 @@
-# 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

@@ -1,104 +0,0 @@
-# Prompt-Base Oficial para IA Trabalhar com Sema
-
-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. A Sema nao foi desenhada para ergonomia humana como prioridade; ela foi desenhada para IA.
-
-## Prompt-base
-
-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 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.
-
-Fontes de verdade, em ordem:
-1. se o projeto expuser `SEMA_CONTEXT.md`, comece por ele
-2. `SEMA_BRIEF.md`
-3. `SEMA_INDEX.json`
-4. README do projeto
-5. gramatica e documentacao de sintaxe da Sema
-6. especificacao semantica da linguagem
-7. exemplos oficiais, com prioridade para o vertical de pagamento
-8. `sema resumo` e `briefing.min.json` quando a IA for pequena
-9. AST, IR e diagnosticos exportados pela CLI em JSON quando a capacidade aguentar
-
-Regras de operacao:
-- preserve o significado semantico
-- use o formatador oficial da Sema como fonte unica de estilo
-- use diagnosticos estruturados como contrato de correcao
-- use a IR como fonte de verdade semantica quando houver duvida
-- nao conclua uma alteracao sem validar e verificar o modulo
-- trate `importar` como bootstrap revisavel, nao como contrato final automatico
-- trate `drift` como medicao de verdade contra codigo vivo
-- trate `impl` como ponte entre task e simbolo real
-- nao invente regra de negocio que o contrato e o codigo nao sustentem
-
-Antes de editar `.sema`, entenda:
-- o module alvo
-- os contratos de task, route, error, effects, guarantees, state e flow
-- os exemplos oficiais relacionados
-
-Depois de editar `.sema`, execute este fluxo:
-1. formatar
-2. validar
-3. diagnosticar, se houver falha
-4. verificar
-
-Se houver conflito entre texto livre e IR/diagnosticos, priorize a IR e os diagnosticos da CLI.
-
-Se algo nao estiver claro, siga a forma ja usada nos exemplos oficiais. Nao improvise sem base.
-```
-
-## Variacao curta
-
-Se voce quiser um prompt menor para uso frequente:
-
-```text
-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:
-
-```text
-Revise este modulo Sema como contrato semantico executavel. Procure incoerencias entre input, output, rules, effects, guarantees, state, flow, route e error. Considere a IR e os diagnosticos da CLI como fonte de verdade. Nao critique estilo fora do que o formatador oficial resolveria automaticamente.
-```
-
-## Variacao para geracao
-
-Use esta versao quando a IA for escrever modulo novo:
-
-```text
-Gere um modulo Sema seguindo a gramatica oficial, os exemplos do projeto e o estilo do formatador canonico. Estruture o modulo como contrato semantico executavel, com blocos explicitos para entrada, saida, regras, efeitos, garantias, erros, estado, fluxo e testes quando fizer sentido. Nao use sintaxe fora do repertorio ja suportado pela linguagem.
-```
-
-## Variacao para correcao guiada por diagnostico
-
-Use esta versao quando a IA ja tiver erro concreto para corrigir:
-
-```text
-Corrija este modulo Sema a partir dos diagnosticos estruturados da CLI. Preserve a intencao do contrato e altere apenas o necessario para eliminar as falhas. Depois da correcao, aplique o formatador oficial e revalide.
-```
-
-## O que sempre anexar junto do prompt
-
-Idealmente, acompanhe o prompt com:
-
-- o arquivo `.sema` alvo
-- o resultado de `sema ast --json`
-- o resultado de `sema ir --json`
-- o resultado de `sema diagnosticos --json`, se houver erro
-- um exemplo oficial parecido
-
-Sem isso, a IA pode ate acertar. Com isso, ela trabalha direito.

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/automacao.sema

@@ -1,107 +0,0 @@
-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
-  }
-}