@semacode/cli 1.3.6 → 1.4.0

package/docs/como-ensinar-a-sema-para-ia.md

@@ -0,0 +1,149 @@
+# Como Ensinar a Sema para IA
+
+Este documento explica como fazer uma IA entender a Sema sem depender de memoria previa do modelo. A estrategia correta nao e presumir que a IA "ja conhece a linguagem", e sim entregar contexto suficiente para ela operar com seguranca.
+
+Leia isso do ponto de vista da CLI publica. A IA nao deve assumir que esta dentro do monorepo da Sema, nem que precisa chamar `node pacotes/cli/dist/index.js`.
+
+## Principio central
+
+Uma IA entende uma linguagem nova quando recebe quatro camadas de contexto:
+
+1. sintaxe
+2. semantica
+3. estrutura intermediaria estavel
+4. exemplos reais
+
+Sem essas quatro camadas, o modelo comeca a adivinhar. E adivinhacao em linguagem de contrato e pedir para nascer bug feio.
+
+Antes de qualquer outra coisa, a IA tambem precisa receber a **moldura correta**:
+
+- a Sema e um protocolo de governanca de intencao
+- a Sema foi feita para IA, nao para ergonomia humana
+- a Sema nao foi feita para "automatizar tudo"
+- a Sema existe para explicitar, alinhar e verificar contrato contra sistema vivo
+- curadoria humana continua parte da proposta
+
+Se a IA errar essa moldura, ela vai cobrar da ferramenta a coisa errada e operar feito um animal apressado.
+
+## Camada 1. Sintaxe
+
+A IA precisa saber como a linguagem e escrita.
+
+Fontes principais:
+
+- [README.md](../README.md)
+- [sintaxe.md](./sintaxe.md)
+- [integracao-com-ia.md](./integracao-com-ia.md)
+
+Objetivo dessa camada:
+
+- reconhecer blocos validos
+- entender delimitadores
+- nao inventar palavras-chave
+- respeitar a organizacao canonicamente formatada
+
+## Camada 2. Semantica
+
+Depois de saber ler, a IA precisa saber o que cada bloco significa.
+
+Fontes principais:
+
+- [README.md](../README.md)
+- [integracao-com-ia.md](./integracao-com-ia.md)
+- [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
+
+Objetivo dessa camada:
+
+- distinguir contrato interno de `task`
+- distinguir contrato publico de `route`
+- entender `effects`, `guarantees`, `error`, `state` e `flow`
+- operar na linguagem como especificacao executavel, nao como texto decorativo
+- entender que `importar` e bootstrap
+- entender que `drift` e regua de coerencia contra o runtime
+- entender que `impl` e ponte rastreavel para simbolo vivo
+
+## Camada 3. Estrutura intermediaria estavel
+
+Essa e a camada que faz a parada parar de ser um cassino.
+
+Em vez de confiar que a IA vai interpretar `.sema` cru de primeira, use a CLI como tradutora oficial da linguagem.
+
+Comandos principais:
+
+```bash
+sema resumo arquivo.sema --micro --para onboarding
+sema validar arquivo.sema --json
+sema diagnosticos arquivo.sema --json
+sema ast arquivo.sema --json
+sema ir arquivo.sema --json
+sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
+```
+
+Como cada comando ajuda:
+
+- `resumo`: entrega cartao semantico pequeno para IA com janela curta
+- `validar --json`: diz se a base esta semanticamente valida
+- `diagnosticos --json`: devolve erros e avisos como contrato estruturado
+- `ast --json`: mostra a forma sintatica escrita
+- `ir --json`: mostra a forma semantica resolvida
+- `verificar --json`: mostra o estado operacional do projeto
+
+Se a IA puder consumir `ir --json`, melhor ainda. E ali que a linguagem fica menos ambigua e mais utilizavel para automacao. Mas nao seja um animal: para modelo pequeno, comece em `resumo` e `briefing.min.json`.
+
+## Camada 4. Exemplos reais
+
+Modelo aprende muito por padrao. Por isso, bons exemplos valem quase tanto quanto especificacao.
+
+Arquivos recomendados:
+
+- [pagamento.sema](../exemplos/pagamento.sema)
+- [pagamento_dominio.sema](../exemplos/pagamento_dominio.sema)
+- [automacao.sema](../exemplos/automacao.sema)
+- [tratamento_erro.sema](../exemplos/tratamento_erro.sema)
+- [crud_simples.sema](../exemplos/crud_simples.sema)
+
+O vertical oficial de pagamento deve ser tratado como a referencia principal.
+
+## O que a IA nao deve fazer
+
+- inventar palavras-chave fora da gramatica
+- introduzir blocos inexistentes
+- assumir semantica que nao aparece na especificacao
+- tratar draft importado como contrato final so porque veio da CLI
+- tratar a Sema como gerador magico de sistema completo
+- editar `.sema` sem rodar `sema formatar`
+- encerrar alteracao sem consultar `diagnosticos` quando houver falha
+
+## O que a IA deve fazer
+
+- usar a gramatica e os exemplos como fonte de estilo
+- usar a IR como fonte de verdade semantica sempre que possivel
+- usar diagnosticos estruturados como guia de correcao
+- rodar o formatador antes de considerar o trabalho pronto
+- validar e verificar a mudanca no mesmo fluxo
+
+## Estrategia recomendada
+
+Se voce for instruir uma IA para trabalhar com Sema, entregue o contexto nesta ordem:
+
+1. [README.md](../README.md)
+2. [como-ensinar-a-sema-para-ia.md](./como-ensinar-a-sema-para-ia.md)
+3. [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
+4. [prompt-base-ia-sema.md](./prompt-base-ia-sema.md)
+5. `sema resumo --micro` ou `sema resumo --curto`, conforme a capacidade da IA
+6. `ast --json`, `ir --json` e `diagnosticos --json` do modulo alvo, se a capacidade aguentar
+
+Essa ordem faz a IA ir de contexto geral para contexto operacional, em vez de cair direto num arquivo cru e sair chutando.
+
+## Regra de ouro
+
+A Sema foi desenhada para ser entendida por IA, mas isso nao significa que a IA vai adivinhar sozinha.
+
+Ela entende bem quando recebe:
+
+- especificacao
+- exemplos
+- JSON estrutural
+- feedback automatico
+
+Sem isso, ate o modelo mais caro vira estagiario emocionado.

package/docs/fluxo-pratico-ia-sema.md

@@ -0,0 +1,177 @@
+# Fluxo Pratico para IA Antes de Editar `.sema`
+
+Este documento descreve o fluxo operacional recomendado para qualquer IA antes, durante e depois de alterar arquivos `.sema`.
+
+Se a IA seguir isso, ela trabalha com contexto. Se nao seguir, vira adivinhacao gourmet.
+
+## Fluxo curto
+
+1. ler contexto do projeto
+2. identificar a capacidade da IA
+3. identificar o modulo alvo
+4. consultar o menor artefato semantico suficiente
+5. editar
+6. formatar
+7. validar
+8. verificar
+
+## Fluxo detalhado
+
+### Etapa 1. Ler contexto minimo
+
+Antes de tocar em qualquer arquivo, a IA deve ler:
+
+- [README.md](../README.md)
+- [integracao-com-ia.md](./integracao-com-ia.md)
+- [como-ensinar-a-sema-para-ia.md](./como-ensinar-a-sema-para-ia.md)
+
+Se o trabalho estiver ligado a pagamento, ler tambem:
+
+- [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
+
+### Etapa 2. Escolher a faixa de capacidade
+
+Antes de despejar contexto na IA, escolha o que ela aguenta:
+
+- IA pequena ou gratuita: `sema resumo --micro` e `briefing.min.json`
+- IA media: `sema resumo --curto`, `briefing.min.json` e `drift.json`
+- IA grande: `contexto-ia`, `briefing.json`, `drift.json`, `ir.json` e `ast.json`
+
+### Etapa 3. Ler o modulo alvo e um exemplo parecido
+
+A IA deve identificar:
+
+- qual arquivo sera editado
+- qual modulo esse arquivo representa
+- qual exemplo oficial mais se parece com o que precisa ser feito
+
+Regra pratica:
+
+- automacao: [automacao.sema](../exemplos/automacao.sema)
+- erros e fluxos de falha: [tratamento_erro.sema](../exemplos/tratamento_erro.sema)
+- borda publica e pagamento: [pagamento.sema](../exemplos/pagamento.sema)
+
+### Etapa 4. Consultar AST e IR quando fizer sentido
+
+Antes de alterar, a IA deve executar:
+
+```bash
+sema resumo caminho/arquivo.sema --curto --para mudanca
+sema ast caminho/arquivo.sema --json
+sema ir caminho/arquivo.sema --json
+```
+
+Objetivo:
+
+- ver a forma sintatica quando a capacidade aguentar
+- ver a forma semantica resolvida quando a capacidade aguentar
+- evitar interpretar errado o contrato
+
+### Etapa 5. Editar o `.sema`
+
+Ao editar, a IA deve:
+
+- preservar a intencao do modulo
+- seguir a gramatica existente
+- evitar criar bloco ou operador nao suportado
+- preferir a forma ja usada nos exemplos oficiais
+
+### Etapa 6. Formatar
+
+Depois da edicao:
+
+```bash
+sema formatar caminho/arquivo.sema
+sema formatar caminho/arquivo.sema --check
+```
+
+Se `--check` falhar, o trabalho ainda nao esta pronto.
+
+### Etapa 7. Validar e diagnosticar
+
+Depois da formatacao:
+
+```bash
+sema validar caminho/arquivo.sema --json
+sema diagnosticos caminho/arquivo.sema --json
+```
+
+Se houver falha:
+
+- usar os diagnosticos estruturados como contrato de correcao
+- nao insistir em leitura manual teimosa quando a CLI ja disse onde esta a merda
+
+### Etapa 7.5. Compilar quando a tarefa pedir codigo derivado
+
+Se a tarefa nao for so editar contrato, mas tambem gerar base de implementacao, a IA deve rodar explicitamente:
+
+```bash
+sema compilar caminho/arquivo.sema --alvo typescript --saida ./saida/typescript
+```
+
+Ou trocar o alvo para `python` ou `dart`, conforme o caso.
+
+Regra pratica:
+
+- se a entrega inclui codigo derivado, `sema compilar` nao e opcional
+- se a IA ignorar `compilar`, ela pode acabar reescrevendo na mao coisa que a Sema ja gera sozinha, que e burrice operacional
+
+### Etapa 8. Verificar
+
+No fechamento:
+
+```bash
+sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
+```
+
+## Fluxo minimo para automacao
+
+Se voce quiser o menor fluxo aceitavel para uma IA pequena:
+
+```bash
+sema resumo caminho/arquivo.sema --micro --para mudanca
+sema formatar caminho/arquivo.sema
+sema validar caminho/arquivo.sema --json
+```
+
+Mas, sendo sincero, o fluxo bom mesmo e fechar com `verificar`.
+
+Se a tarefa envolver codigo derivado, o fluxo minimo aceitavel vira:
+
+```bash
+sema ir caminho/arquivo.sema --json
+sema formatar caminho/arquivo.sema
+sema validar caminho/arquivo.sema --json
+sema compilar caminho/arquivo.sema --alvo typescript --saida ./saida/typescript
+```
+
+## Checklist de saida
+
+Antes de considerar a alteracao pronta, a IA deve responder mentalmente:
+
+- eu entendi o modulo e o contrato?
+- eu mantive a sintaxe dentro do que a linguagem suporta?
+- eu formatei o arquivo?
+- eu validei?
+- eu olhei diagnosticos se algo falhou?
+- eu fechei com verificacao?
+
+Se alguma resposta for "nao", ainda nao terminou.
+
+## Regra de ouro
+
+Em Sema, a IA nao deveria operar no escuro.
+
+Ela deve trabalhar sempre com:
+
+- exemplo oficial
+- AST
+- IR
+- diagnosticos
+- formatador
+
+Esse conjunto e o que faz a linguagem ser amigavel para IA de verdade, e nao so no discurso bonito.
+
+## Observacao sobre caminhos
+
+Esta documentacao usa placeholders de arquivo e pasta, nao caminhos do monorepo da Sema. A IA deve adaptar isso ao projeto atual e continuar tratando `sema` como interface publica principal.

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

@@ -0,0 +1,108 @@
+# Instalacao e Primeiro Uso
+
+Este guia cobre o caminho publico atual da Sema para CLI, MCP e extensao.
+
+## Requisitos
+
+- Node.js LTS
+- npm funcional
+- Python 3 so se voce quiser rodar testes Python gerados
+
+## CLI
+
+Instalacao principal:
+
+```bash
+npm install -g @semacode/cli
+sema --help
+sema doctor
+```
+
+Instalacao por release:
+
+```bash
+npm install -g https://github.com/gerlanss/Sema/releases/latest/download/sema-cli-latest.tgz
+```
+
+Instalacao local ao projeto:
+
+```bash
+npm install @semacode/cli
+npx sema --help
+```
+
+## MCP
+
+Se voce usa cliente MCP:
+
+```bash
+npm install -g @semacode/mcp
+sema-mcp
+```
+
+Ou sem instalar:
+
+```bash
+npx -y @semacode/mcp
+```
+
+## Instaladores oficiais
+
+Linux ou macOS:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/gerlanss/Sema/v1.4.0/install-sema.sh | bash
+curl -fsSL https://raw.githubusercontent.com/gerlanss/Sema/v1.4.0/install-sema.sh | bash -s -- --with-vscode --with-mcp
+```
+
+Windows PowerShell:
+
+```powershell
+Invoke-WebRequest -Uri https://raw.githubusercontent.com/gerlanss/Sema/v1.4.0/install-sema.ps1 -OutFile install-sema.ps1
+.\install-sema.ps1 -WithVSCode -WithMcp -Version 1.4.0
+```
+
+Se quiser outra tag, troque `v1.4.0` pelo release desejado.
+
+## Extensao VS Code
+
+```bash
+curl -L -o sema-language-tools.vsix https://github.com/gerlanss/Sema/releases/latest/download/sema-language-tools-latest.vsix
+code --install-extension ./sema-language-tools.vsix --force
+```
+
+Ou baixe a VSIX antes e instale localmente.
+
+## Primeiro teste
+
+```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 ir contratos/pedidos.sema --json
+sema formatar contratos/pedidos.sema
+sema verificar contratos --saida ./.tmp/verificacao
+```
+
+## Primeiro fluxo IA-first
+
+```bash
+sema inspecionar . --json
+sema resumo contratos/pedidos.sema --micro --para onboarding
+sema drift contratos/pedidos.sema --json
+sema contexto-ia contratos/pedidos.sema --saida ./.tmp/contexto --json
+```
+
+## Primeiro fluxo de persistencia vendor-first
+
+```bash
+sema validar contratos/sema/persistencia_vendor_first.sema --json
+sema ir contratos/sema/persistencia_vendor_first.sema --json
+```

package/docs/integracao-com-ia.md

@@ -0,0 +1,71 @@
+# Integracao com IA
+
+Sema foi feita para IA operar software vivo com menos adivinhacao.
+
+## Ordem recomendada
+
+1. `sema inspecionar . --json`
+2. `sema resumo <arquivo-ou-pasta> --micro --para onboarding`
+3. `sema drift <arquivo-ou-pasta> --json`
+4. `sema contexto-ia <arquivo.sema> --saida <diretorio> --json`
+
+Nao comece cavando codigo bruto quando a ferramenta ja consegue te dar contrato, score, lacuna e superficie viva.
+
+## Por capacidade do modelo
+
+IA pequena:
+
+- `sema resumo --micro`
+- `briefing.min.json`
+- `prompt-curto.txt`
+
+IA media:
+
+- `sema resumo --curto`
+- `drift.json`
+- `briefing.min.json`
+
+IA grande:
+
+- `sema contexto-ia`
+- `briefing.json`
+- `ir.json`
+- `ast.json`
+
+## MCP
+
+Se o agente usa MCP:
+
+```bash
+npm install -g @semacode/cli @semacode/mcp
+```
+
+Depois configure:
+
+```json
+{
+  "mcpServers": {
+    "sema": {
+      "command": "npx",
+      "args": ["-y", "@semacode/mcp"]
+    }
+  }
+}
+```
+
+## Regras praticas
+
+- trate `.sema` e IR como fonte de verdade semantica
+- trate `drift` como juiz da adocao incremental
+- use `briefing.min.json` antes de abrir dezenas de arquivos
+- nao invente sintaxe fora da gramatica oficial
+- em persistencia, nao assuma que bancos diferentes tem o mesmo contrato operacional
+
+## Arquivos uteis no repo
+
+- `AGENTS.md`
+- `llms.txt`
+- `llms-full.txt`
+- `SEMA_BRIEF.md`
+- `SEMA_INDEX.json`
+- `docs/persistencia-vendor-first.md`

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.