@semacode/cli 0.8.2 → 0.8.3

package/README.md

@@ -20,7 +20,7 @@ sema --help
 ## Instalacao via tarball da release
 
 ```bash
-npm install -g ./sema-cli-0.8.2.tgz
+npm install -g ./sema-cli-0.8.3.tgz
 ```
 
 Ou direto da GitHub Release:
@@ -39,7 +39,7 @@ npx sema --help
 Ou, se voce estiver testando um tarball local:
 
 ```bash
-npm install ./sema-cli-0.8.2.tgz
+npm install ./sema-cli-0.8.3.tgz
 npx sema --help
 ```
 

package/docs/AGENT_STARTER.md

@@ -0,0 +1,63 @@
+# AGENT_STARTER
+
+Use este texto como starter curto para qualquer IA antes de editar `.sema`.
+
+```text
+Voce esta trabalhando com Sema, um Protocolo de Governanca de Intencao para IA e backend vivo.
+
+Importante:
+- a Sema modela contratos, estados, fluxos, erros, efeitos e garantias
+- a Sema gera codigo e scaffolding real para TypeScript, Python e Dart
+- a Sema pode servir de base para interfaces graficas elegantes e coerentes
+- a Sema nao gera uma interface completa sozinha no estado atual
+- trate a Sema como cerebro semantico da aplicacao, nao como gerador magico de front-end pronto
+- se a tarefa envolver UI, prefira pedir Sema + React + TypeScript ou Sema + arquitetura de front-end
+- evite pedir HTML unico solto quando a intencao for testar a Sema de verdade
+
+Regras:
+- nao invente sintaxe fora da gramatica e dos exemplos oficiais
+- trate `ir --json` como fonte de verdade semantica
+- trate `diagnosticos --json` como fonte de correcao
+- use `sema formatar` como fonte unica de estilo
+- preserve a intencao do contrato
+
+Comandos essenciais:
+- contexto completo do modulo: `sema contexto-ia <arquivo.sema>`
+- estrutura sintatica: `sema ast <arquivo.sema> --json`
+- estrutura semantica: `sema ir <arquivo.sema> --json`
+- validacao: `sema validar <arquivo.sema> --json`
+- diagnosticos: `sema diagnosticos <arquivo.sema> --json`
+- formatacao: `sema formatar <arquivo.sema>`
+- importacao assistida de legado: `sema importar <nestjs|fastapi|flask|typescript|python|dart> <diretorio> --saida <diretorio>`
+- geracao de codigo: `sema compilar <arquivo-ou-pasta> --alvo <typescript|python|dart> --saida <diretorio>`
+- verificacao final: `sema verificar <arquivo-ou-pasta> [--json]`
+
+Regra pratica de ouro:
+- se a tarefa pedir codigo derivado, `sema compilar` e obrigatorio
+- se a tarefa partir de projeto que nao nasceu com Sema, `sema importar` deve entrar antes da lapidacao semantica
+- se a tarefa pedir apenas leitura ou correcao sem gerar codigo, `sema compilar` pode ficar fora
+
+Antes de editar:
+1. leia README, docs de IA e um exemplo oficial parecido
+2. consulte AST e IR do modulo alvo
+
+Depois de editar:
+1. rode `sema formatar`
+2. rode `sema validar --json`
+3. se houver falha, use `diagnosticos --json`
+4. se a tarefa pedir codigo derivado, rode `sema compilar`
+5. feche com `sema verificar` ou `npm run project:check`
+
+Priorize sempre:
+- exemplos oficiais
+- JSON da CLI
+- consistencia semantica
+
+Nao improvise quando faltar contexto.
+```
+
+Documentos de apoio:
+
+- [como-ensinar-a-sema-para-ia.md](./como-ensinar-a-sema-para-ia.md)
+- [prompt-base-ia-sema.md](./prompt-base-ia-sema.md)
+- [fluxo-pratico-ia-sema.md](./fluxo-pratico-ia-sema.md)

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

@@ -0,0 +1,129 @@
+# 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.
+
+## 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.
+
+## Camada 1. Sintaxe
+
+A IA precisa saber como a linguagem e escrita.
+
+Fontes principais:
+
+- [gramatica-inicial.md](./gramatica-inicial.md)
+- [sintaxe.md](./sintaxe.md)
+- [gramatica.ebnf](../pacotes/nucleo/src/parser/gramatica.ebnf)
+
+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)
+- [especificacao-inicial.md](./especificacao-inicial.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
+
+## 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
+node pacotes/cli/dist/index.js validar arquivo.sema --json
+node pacotes/cli/dist/index.js diagnosticos arquivo.sema --json
+node pacotes/cli/dist/index.js ast arquivo.sema --json
+node pacotes/cli/dist/index.js ir arquivo.sema --json
+node pacotes/cli/dist/index.js verificar exemplos --json --saida ./.tmp/verificacao-ia
+```
+
+Como cada comando ajuda:
+
+- `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.
+
+## 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 de pagamento do `0.5` 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
+- 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. `ast --json`, `ir --json` e `diagnosticos --json` do modulo alvo
+
+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,173 @@
+# 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 o modulo alvo
+3. consultar AST e IR
+4. editar
+5. formatar
+6. validar
+7. 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. 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 3. Consultar AST e IR
+
+Antes de alterar, a IA deve executar:
+
+```bash
+node pacotes/cli/dist/index.js ast caminho\\arquivo.sema --json
+node pacotes/cli/dist/index.js ir caminho\\arquivo.sema --json
+```
+
+Objetivo:
+
+- ver a forma sintatica
+- ver a forma semantica resolvida
+- evitar interpretar errado o contrato
+
+### Etapa 4. 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 5. Formatar
+
+Depois da edicao:
+
+```bash
+node pacotes/cli/dist/index.js formatar caminho\\arquivo.sema
+node pacotes/cli/dist/index.js formatar caminho\\arquivo.sema --check
+```
+
+Se `--check` falhar, o trabalho ainda nao esta pronto.
+
+### Etapa 6. Validar e diagnosticar
+
+Depois da formatacao:
+
+```bash
+node pacotes/cli/dist/index.js validar caminho\\arquivo.sema --json
+node pacotes/cli/dist/index.js 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 6.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
+node pacotes/cli/dist/index.js 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 7. Verificar
+
+No fechamento:
+
+```bash
+node pacotes/cli/dist/index.js verificar exemplos --json --saida ./.tmp/verificacao-ia
+```
+
+Ou, no fluxo consolidado do projeto:
+
+```bash
+npm run project:check
+```
+
+## Fluxo minimo para automacao
+
+Se voce quiser o menor fluxo aceitavel para uma IA:
+
+```bash
+node pacotes/cli/dist/index.js ir caminho\\arquivo.sema --json
+node pacotes/cli/dist/index.js formatar caminho\\arquivo.sema
+node pacotes/cli/dist/index.js 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
+node pacotes/cli/dist/index.js ir caminho\\arquivo.sema --json
+node pacotes/cli/dist/index.js formatar caminho\\arquivo.sema
+node pacotes/cli/dist/index.js validar caminho\\arquivo.sema --json
+node pacotes/cli/dist/index.js 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 caminhos relativos ao repositorio, nao caminhos locais de maquina. Isso permite que qualquer pessoa clone o projeto e use os links e referencias sem depender de uma pasta especifica no proprio ambiente.

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

@@ -0,0 +1,88 @@
+# 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.
+
+## Prompt-base
+
+Use o texto abaixo como base:
+
+```text
+Voce esta trabalhando com Sema, uma DSL semantica orientada a contrato, desenhada para facilitar entendimento e operacao por IA.
+
+Trate a Sema como linguagem de especificacao executavel. Nao invente sintaxe, palavras-chave ou blocos fora da gramatica e dos exemplos oficiais.
+
+Fontes de verdade, em ordem:
+1. README do projeto
+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
+
+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
+
+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.
+```
+
+## 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/node_modules/@sema/gerador-dart/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/gerador-dart",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/node_modules/@sema/gerador-python/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/gerador-python",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/node_modules/@sema/gerador-typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/gerador-typescript",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/node_modules/@sema/nucleo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/nucleo",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/node_modules/@sema/padroes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/padroes",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semacode/cli",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "CLI do Protocolo de Governanca de Intencao Sema para validar contratos, medir drift e operar backend vivo.",
   "type": "module",
   "icon": "logo.png",
@@ -35,16 +35,17 @@
   "types": "dist/index.d.ts",
   "files": [
     "dist",
+    "docs",
     "logo.png",
     "README.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@sema/nucleo": "0.8.2",
-    "@sema/gerador-dart": "0.8.2",
-    "@sema/gerador-python": "0.8.2",
-    "@sema/gerador-typescript": "0.8.2",
-    "@sema/padroes": "0.8.2",
+    "@sema/nucleo": "0.8.3",
+    "@sema/gerador-dart": "0.8.3",
+    "@sema/gerador-python": "0.8.3",
+    "@sema/gerador-typescript": "0.8.3",
+    "@sema/padroes": "0.8.3",
     "typescript": "^5.8.3"
   },
   "bundledDependencies": [