@semacode/cli 0.8.8 → 1.0.0

package/docs/instalacao-e-primeiro-uso.md

@@ -0,0 +1,189 @@
+# Instalacao e Primeiro Uso
+
+Este guia mostra o caminho mais curto para testar a Sema do jeito certo, sem misturar fluxo de usuario com gambiarra de contribuinte.
+
+## Requisitos
+
+- Node.js instalado
+- npm funcionando
+- Python 3 e `pytest` se voce quiser rodar o fluxo completo de testes Python gerados
+
+O repositorio so e necessario se voce quiser contribuir na Sema, rodar o showcase oficial localmente ou empacotar release.
+
+## Caminho oficial
+
+Instalacao via npm:
+
+```bash
+npm install -g @semacode/cli
+sema --help
+sema doctor
+```
+
+Se preferir o tarball oficial da GitHub Release:
+
+```bash
+npm install -g https://github.com/gerlanss/Sema/releases/latest/download/sema-cli-latest.tgz
+sema --help
+sema doctor
+```
+
+Instalacao local ao projeto:
+
+```bash
+npm install @semacode/cli
+npx sema --help
+```
+
+Instaladores auxiliares para a linha publica atual:
+
+- Linux/macOS: `curl -fsSL https://raw.githubusercontent.com/gerlanss/Sema/v1.0.0/install-sema.sh | bash`
+- Windows PowerShell: `irm https://raw.githubusercontent.com/gerlanss/Sema/v1.0.0/install-sema.ps1 | iex`
+
+Se voce quiser reproducao estrita, prefira o npm registry ou o tarball da GitHub Release.
+
+## Primeiro teste sem clonar o repo
+
+```bash
+mkdir sema-demo
+cd sema-demo
+sema iniciar
+sema validar contratos/pedidos.sema --json
+```
+
+## Primeiro fluxo util
+
+```bash
+sema validar contratos/pedidos.sema --json
+sema ast contratos/pedidos.sema --json
+sema ir contratos/pedidos.sema --json
+sema formatar contratos/pedidos.sema
+sema verificar contratos --saida ./.tmp/verificacao
+```
+
+## Primeiro fluxo de IA real
+
+Sem clonar o repo, o fluxo que mais mostra a proposta da Sema hoje e:
+
+```bash
+sema inspecionar . --json
+sema resumo contratos/pedidos.sema --micro --para mudanca
+sema drift contratos/pedidos.sema --json
+sema contexto-ia contratos/pedidos.sema --saida ./.tmp/contexto-pedidos --json
+```
+
+Esse fluxo mostra:
+
+- base de projeto resolvida
+- cartao semantico curto para IA pequena ou gratuita
+- codigo vivo detectado
+- `impl` e `vinculos` resolvidos
+- score, confianca e lacunas do `drift`
+- `briefing.min.json` e `briefing.json` para IA antes da edicao
+
+## `sema.config.json`
+
+Exemplo de configuracao para projeto real:
+
+```json
+{
+  "origens": ["./contratos"],
+  "saida": "./generated",
+  "alvos": ["typescript", "python"],
+  "alvoPadrao": "typescript",
+  "estruturaSaida": "backend",
+  "framework": "nestjs",
+  "modoEstrito": true,
+  "diretoriosSaidaPorAlvo": {
+    "typescript": "./generated/nestjs",
+    "python": "./generated/fastapi"
+  },
+  "convencoesGeracaoPorProjeto": "backend"
+}
+```
+
+## Gerar codigo
+
+Scaffold base:
+
+```bash
+sema compilar contratos/pedidos.sema --alvo typescript --saida ./saida/typescript
+sema compilar contratos/pedidos.sema --alvo python --saida ./saida/python
+sema compilar contratos/pedidos.sema --alvo dart --saida ./saida/dart
+```
+
+Scaffold backend:
+
+```bash
+sema compilar contratos/pedidos.sema --alvo typescript --framework nestjs --estrutura backend --saida ./generated/nestjs
+sema compilar contratos/pedidos.sema --alvo python --framework fastapi --estrutura backend --saida ./generated/fastapi
+```
+
+## Extensao VS Code
+
+Empacotar:
+
+```bash
+npm run extensao:empacotar
+```
+
+Instalar localmente:
+
+```bash
+npm run extensao:instalar-local
+```
+
+Ou manualmente:
+
+```bash
+code --install-extension .tmp/editor-vscode/sema-language-tools-1.0.0.vsix --force
+```
+
+## Caminho de contribuinte
+
+Se o objetivo for desenvolver a propria Sema:
+
+```bash
+npm install
+npm run build
+npm run cli:instalar-local
+sema validar exemplos/calculadora.sema
+```
+
+Se quiser validar tudo de cara:
+
+```bash
+npm run project:check
+```
+
+## `npm link` continua existindo
+
+Esse fluxo continua util, mas e trilha de contribuinte:
+
+```powershell
+npm run cli:instalar-local
+```
+
+Serve para:
+
+- testar a experiencia de terminal no proprio ambiente
+- desenvolver a CLI
+- usar `sema` como interface principal mesmo durante o desenvolvimento local
+
+Para remover:
+
+```powershell
+npm run cli:desinstalar-local
+```
+
+## Resumo honesto
+
+Hoje o jeito certo de testar a Sema e:
+
+1. instalar a CLI pelo npm ou pela GitHub Release
+2. rodar `sema iniciar`
+3. validar `contratos/pedidos.sema`
+4. usar `inspecionar -> resumo -> drift -> contexto-ia` quando o projeto for vivo
+5. ler `briefing.min.json` ou `briefing.json` antes de mandar a IA sair cavando arquivo
+
+Clone + build + `npm link` continua bom para oficina, nao para landing page publica.

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: