@semacode/cli 0.9.0 → 1.1.0

package/docs/integracao-com-ia.md

@@ -0,0 +1,228 @@
+# Integracao com IA
+
+A Sema foi desenhada para IA editar backend vivo com menos chute. O ponto nao e "a IA gera tudo"; o ponto e deixar contrato, vinculo e contexto operacional estruturados o bastante para a IA nao trabalhar igual um bicho tonto. Leitura humana continua possivel, mas nao e o centro do desenho.
+
+## Moldura correta
+
+Se uma IA tratar a Sema como enfeite declarativo, ela vai usar mal. A moldura certa e esta:
+
+- `impl` liga intencao a simbolo executavel
+- `vinculos` ligam contrato a arquivo, simbolo, recurso e superficie real
+- `execucao` explicita timeout, retry, compensacao e criticidade
+- `drift` mede verdade contra codigo vivo
+- `contexto-ia` empacota briefing operacional antes da edicao
+
+Em resumo: a Sema nao serve para a IA adivinhar melhor. Ela serve para a IA precisar adivinhar menos.
+
+## Fluxo recomendado
+
+Quando o trabalho cair em projeto vivo, o fluxo canonico agora e:
+
+```bash
+sema inspecionar . --json
+sema resumo contratos/modulo.sema --micro --para mudanca
+sema drift contratos/modulo.sema --json
+sema contexto-ia contratos/modulo.sema --saida ./.tmp/contexto --json
+```
+
+Leitura rapida:
+
+1. `inspecionar` descobre base do projeto, diretorios de codigo, fontes legado e modulos relevantes.
+2. `resumo` entrega o menor cartao semantico util para a IA atual.
+3. `drift` mede impls, vinculos, rotas, recursos, score semantico e confianca.
+4. `contexto-ia` gera o pacote que a IA deveria ler antes de editar.
+
+## Capacidade da IA
+
+A Sema agora assume explicitamente que nem toda IA aguenta o pacote completo.
+
+- IA pequena ou gratuita: comece em `resumo.micro.txt`, `briefing.min.json` e `prompt-curto.txt`
+- IA media: suba para `resumo.curto.txt`, `briefing.min.json` e `drift.json`
+- IA grande ou com tool use: leia `README.md`, `resumo.md`, `briefing.json`, `drift.json`, `ir.json` e `ast.json`
+
+Se voce joga `ast.json` inteiro em modelo pequeno e depois reclama da resposta, foi voce que fez cagada operacional.
+
+## O que a IA deve consumir
+
+No minimo, para IA pequena:
+
+- `resumo.micro.txt`
+- `briefing.min.json`
+
+No minimo, para IA media:
+
+- `resumo.curto.txt`
+- `briefing.min.json`
+- `drift.json`
+
+No minimo, para IA grande:
+
+- `ir.json`
+- `drift.json`
+- `briefing.json`
+- o proprio contrato `.sema`
+
+O `briefing.json` agora e a peca mais operacional do pacote. Ele responde perguntas que agente serio precisa responder antes de mexer em codigo:
+
+- o que tocar
+- o que validar
+- o que esta frouxo
+- o que foi inferido
+- quais simbolos estao relacionados
+- quais superficies publicas podem ser afetadas
+- quais testes minimos rodar
+
+## Saida relevante do pacote `contexto-ia`
+
+Hoje o pacote pode incluir:
+
+- `resumo.micro.txt`
+- `resumo.curto.txt`
+- `resumo.md`
+- `briefing.min.json`
+- `prompt-curto.txt`
+- `ast.json`
+- `ir.json`
+- `diagnosticos.json`
+- `drift.json`
+- `briefing.json`
+- `README.md`
+- `impl.<origem>.txt` quando existir implementacao vinculada
+
+## Score, confianca e risco
+
+`drift`, `inspecionar` e `contexto-ia` passam a expor sinais que ajudam a IA a nao tratar rascunho como verdade absoluta:
+
+- `scoreSemantico`
+- `confiancaVinculo`
+- `riscoOperacional`
+- `lacunas`
+- `vinculos_validos`
+- `vinculos_quebrados`
+
+Leitura pratica:
+
+- score alto + confianca alta: a IA pode editar com trilha boa
+- score medio: ainda precisa ler contrato e conferir codigo vivo
+- vinculo quebrado: a IA deve reduzir ousadia e consertar rastreabilidade antes de refatorar igual doida
+
+## Superficies que a IA pode esperar
+
+A linguagem agora trata estas bordas como primeira classe:
+
+- `route`
+- `worker`
+- `evento`
+- `fila`
+- `cron`
+- `webhook`
+- `cache`
+- `storage`
+- `policy`
+
+Isso importa porque backend real nao vive so de HTTP. Se a IA vai editar stack viva, ela precisa enxergar job, evento, webhook e recurso assincrono como parte do contrato, nao como sobra esquecida no runtime.
+
+## Contrato operacional
+
+Dentro de `task` e superficies, a IA deve prestar atencao em:
+
+- `input`
+- `output`
+- `effects`
+- `impl`
+- `vinculos`
+- `execucao`
+- `guarantees`
+- `error`
+
+Exemplo minimo:
+
+```sema
+task medir_drift {
+  input {
+    contrato: Texto required
+  }
+  output {
+    score: Decimal
+  }
+  impl {
+    ts: cli.src.drift.analisarDriftLegado
+  }
+  vinculos {
+    arquivo: "pacotes/cli/src/drift.ts"
+    simbolo: cli.src.drift.analisarDriftLegado
+  }
+  execucao {
+    timeout: "30s"
+    retry: "3x exponencial"
+    criticidade_operacional: alta
+  }
+  guarantees {
+    score existe
+  }
+}
+```
+
+## Comandos que agente serio nao deveria ignorar
+
+- `sema ast arquivo.sema --json`
+- `sema ir arquivo.sema --json`
+- `sema validar arquivo.sema --json`
+- `sema diagnosticos arquivo.sema --json`
+- `sema formatar arquivo.sema`
+- `sema inspecionar [arquivo-ou-pasta] --json`
+- `sema drift [arquivo-ou-pasta] --json`
+- `sema contexto-ia arquivo.sema [--saida <diretorio>] --json`
+- `sema verificar [arquivo-ou-pasta] --json`
+
+## Fluxos comuns
+
+Quando a tarefa for so modelagem:
+
+```bash
+sema ast contratos/pedidos.sema --json
+sema ir contratos/pedidos.sema --json
+sema formatar contratos/pedidos.sema
+sema validar contratos/pedidos.sema --json
+```
+
+Quando a tarefa envolver codigo derivado:
+
+```bash
+sema inspecionar . --json
+sema drift contratos/pedidos.sema --json
+sema contexto-ia contratos/pedidos.sema --saida ./.tmp/contexto-pedidos --json
+sema compilar contratos/pedidos.sema --alvo typescript --framework nestjs --estrutura backend --saida ./generated/nestjs
+```
+
+Quando a tarefa nasce num legado:
+
+```bash
+sema importar flask ./backend-flask --saida ./sema/importado --json
+sema formatar ./sema/importado
+sema validar ./sema/importado --json
+sema drift ./sema/importado --json
+```
+
+## Showcase oficial do repo
+
+Se voce estiver no monorepo da Sema, o showcase [showcases/ranking-showroom](../showcases/ranking-showroom/) continua sendo a melhor vitrine do fluxo completo:
+
+```bash
+cd showcases/ranking-showroom
+sema inspecionar . --json
+sema drift contratos/ranking_showroom.sema --json
+sema contexto-ia contratos/ranking_showroom.sema --saida ./.tmp/contexto-ranking --json
+```
+
+O valor aqui nao e so "validou". O valor e sair com score, confianca, drift e briefing suficientes para editar o backend Flask real sem sair cavando arquivo a esmo.
+
+## Fechamento operacional
+
+Quando a IA terminar a mudanca fora do monorepo:
+
+```bash
+sema formatar contratos/modulo.sema
+sema validar contratos/modulo.sema --json
+sema verificar contratos --json --saida ./.tmp/verificacao-final
+```

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