@semacode/cli 1.5.16 → 1.5.18

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

@@ -0,0 +1,165 @@
+# 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
+- seguranca e autorizacao
+- classificacao de dados
+- segredos e proibicoes explicitas
+- regras
+- efeitos operacionais
+- execucao, idempotencia, retry e compensacao
+- transicoes de estado
+- orquestracao
+- erros publicos
+- testes executaveis com saida, status ou erro observavel
+
+## 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:
+
+- exige `authz`
+- classifica `dados`
+- declara `segredos`, `audit` e `forbidden`
+- valida entrada
+- consulta o gateway
+- persiste o pagamento
+- emite evento
+- notifica comprovante
+- registra auditoria
+- declara `execucao` com idempotencia, timeout, retry, compensacao e criticidade
+- 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 superficie sensivel sem deixar seguranca invisivel
+- modela efeitos operacionais
+- modela falhas reais
+- modulariza dominio com `use`
+- declara idempotencia e execucao critica sem criar sintaxe nova
+- 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/persistencia-vendor-first.md

@@ -0,0 +1,145 @@
+# Persistencia Vendor-First
+
+Sema 1.5.18 trata banco como superficie semantica de primeira classe. Isso significa assumir diferencas reais entre engines e coloca-las no contrato, no semantico, na IR, no drift, no impact map, na renomeacao assistida, no `verificar` e na extensao. Nesta linha, o `drift` tambem materializa persistencia local real em `Preferences`, `localStorage` e `sessionStorage` quando a task esta ancorada no arquivo que usa essas APIs, preservando o framing IA-first da release atual.
+
+## Engines publicas
+
+- `postgres`
+- `mysql`
+- `sqlite`
+- `mongodb`
+- `redis`
+
+## Exemplo PostgreSQL
+
+```sema
+database principal_postgres {
+  engine: postgres
+  schema: public
+  consistency: forte
+  durability: alta
+  transaction_model: mvcc
+  query_model: sql
+  capabilities {
+    joins
+    views
+    foreign_keys
+  }
+  table pedidos {
+    entity: Pedido
+  }
+  relationship pedido_cliente {
+    from: Pedido
+    to: Cliente
+  }
+  query buscar_pedidos {
+    mode: sql
+  }
+}
+```
+
+## Exemplo MySQL
+
+```sema
+database principal_mysql {
+  engine: mysql
+  consistency: forte
+  durability: alta
+  transaction_model: bloqueio
+  query_model: sql
+  table faturamento {
+    table: faturamento
+  }
+  index faturamento_status {
+    table: faturamento
+  }
+  query buscar_faturas {
+    mode: sql
+  }
+}
+```
+
+## Exemplo SQLite
+
+```sema
+database principal_sqlite {
+  engine: sqlite
+  consistency: snapshot
+  durability: media
+  transaction_model: single_thread
+  query_model: sql
+  table cache_local {
+    table: cache_local
+  }
+  retention limpeza_local {
+    retention: "7d"
+  }
+}
+```
+
+## Exemplo MongoDB
+
+```sema
+database principal_mongodb {
+  engine: mongodb
+  consistency: eventual
+  durability: alta
+  transaction_model: documento
+  query_model: documento
+  collection pedidos {
+    collection: pedidos
+  }
+  document pedido_snapshot {
+    entity: PedidoSnapshot
+  }
+  query pipeline_pedido {
+    mode: pipeline
+  }
+}
+```
+
+## Exemplo Redis
+
+```sema
+database principal_redis {
+  engine: redis
+  consistency: eventual
+  durability: media
+  transaction_model: single_thread
+  query_model: chave_valor
+  keyspace cache_pedidos {
+    ttl: "300s"
+  }
+  stream eventos_pedido {
+    surface: fila
+  }
+  retention expurgo_cache {
+    retention: "300s"
+  }
+}
+```
+
+## Compatibilidade calculada
+
+Cada recurso recebe compatibilidade por engine:
+
+- `nativo`
+- `adaptado`
+- `parcial`
+- `invalido`
+
+Isso deixa explicito quando o contrato esta pedindo portabilidade falsa, por exemplo:
+
+- `table` em `redis`
+- `foreign_keys` em engine sem suporte equivalente
+- transacao multi-documento tratada como universal
+
+## Onde isso aparece
+
+- parser e AST
+- IR canonica
+- analisador semantico
+- formatador
+- `sema drift`
+- `sema importar`
+- extensao VS Code

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

@@ -0,0 +1,105 @@
+# 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. Humanos escrevem, revisam e aprovam; o consumidor primario e o agente.
+
+## Prompt-base
+
+Use o texto abaixo como base:
+
+```text
+Voce esta trabalhando com Sema, um contrato semantico IA-first para agentes operarem software vivo.
+
+Tecnicamente, a Sema funciona como linguagem de intencao orientada a contrato. Operacionalmente, ela existe para governar semantica acima da stack e traduzir intencao operacional para IA, nao para substituir arquitetura, design ou aprovacao humana.
+
+Trate a Sema como contrato semantico executavel e protocolo de governanca IA-first. 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
+- use `predicadoCanonico` como normalizacao opcional; preserve o `predicado` original
+- 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 contrato semantico IA-first orientado a agente. 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/rollback.md

@@ -0,0 +1,47 @@
+# Rollback
+
+Rollback de release publica da Sema deve preservar rastreabilidade. NPM nao deve ser tratado como pasta temporaria: apagar versao publicada e medida extrema e limitada.
+
+## Quando aplicar
+
+- CLI ou MCP publicados quebram instalacao basica.
+- VSIX publicada nao inicia ou quebra o Language Server.
+- Instaladores baixam asset errado.
+- Release notes ou checksums apontam para artefato invalido.
+
+## Primeira resposta
+
+1. Marque o problema no GitHub Release.
+2. Reponte `latest` no NPM para a ultima versao boa, quando necessario:
+
+```bash
+npm dist-tag add @semacode/cli@<versao-boa> latest
+npm dist-tag add @semacode/mcp@<versao-boa> latest
+```
+
+3. Se o problema for so VSIX ou asset de release, substitua o asset no GitHub Release ou publique uma release patch.
+4. Prefira publicar patch corretivo (`1.5.18`, por exemplo) quando o pacote ja saiu para usuarios.
+
+## Validacao de rollback
+
+```bash
+npm view @semacode/cli dist-tags --json
+npm view @semacode/mcp dist-tags --json
+npm install -g @semacode/cli@latest
+npm install -g @semacode/mcp@latest
+sema --version
+sema-mcp --help
+```
+
+## Git
+
+Se o commit foi empurrado mas a release falhou antes de publicar NPM, corrija com novo commit. Evite reescrever `main` depois de push publico.
+
+Se o tag foi criado errado e ainda nao existe release consumida:
+
+```bash
+git tag -d v<versao>
+git push origin :refs/tags/v<versao>
+```
+
+Use isso somente antes de usuarios consumirem o tag.

package/docs/sintaxe.md

@@ -0,0 +1,212 @@
+# Sintaxe Canonica
+
+A Sema usa blocos declarativos previsiveis para reduzir ambiguidade no parser, na IR, no drift e no contexto de IA. A escrita humana pode ser legivel, mas o alvo principal da sintaxe e gerar contrato consumivel por agente.
+
+## Regras basicas
+
+- um arquivo `.sema` contem um `module` principal
+- cada bloco abre com palavra-chave e fecha com `}`
+- campos usam `nome: valor`
+- blocos declarativos podem aparecer aninhados quando o contrato exigir
+- `tests` usa blocos `caso`
+
+## Blocos de primeira classe
+
+- `module`
+- `use`
+- `database`
+- `type`
+- `entity`
+- `enum`
+- `state`
+- `task`
+- `flow`
+- `route`
+- `worker`
+- `evento`
+- `fila`
+- `cron`
+- `webhook`
+- `cache`
+- `storage`
+- `policy`
+- `tests`
+- `docs`
+- `comments`
+
+## Subblocos comuns
+
+- `input`
+- `output`
+- `rules`
+- `effects`
+- `auth`
+- `authz`
+- `dados`
+- `audit`
+- `segredos`
+- `forbidden`
+- `impl`
+- `vinculos`
+- `execucao`
+- `guarantees`
+- `error`
+- `fields`
+- `invariants`
+- `transitions`
+- `given`
+- `when`
+- `expect`
+
+## Tipos primitivos
+
+Tipos primitivos reconhecidos diretamente:
+
+- `Texto`
+- `Numero`
+- `Inteiro`
+- `Decimal`
+- `Booleano`
+- `Data`
+- `Timestamp`
+- `Objeto`
+- `Id`
+- `Email`
+- `Json`
+
+`Timestamp` e `Objeto` funcionam como aliases primitivos suportados e preservam o texto original na IR.
+
+## Tipos compostos
+
+```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?`
+
+## Predicados normalizados
+
+Predicados escritos em contrato preservam o texto original em `predicado`. Quando a CLI reconhece uma forma comum, a expressao estruturada pode expor tambem `predicadoCanonico`.
+
+Exemplo:
+
+```sema
+rules {
+  email deve_ser email_valido
+  nome deve_ser preenchido
+}
+```
+
+Na IR, `email_valido` continua existindo como escrito e pode receber uma normalizacao como `valid_email`; `preenchido` pode receber `filled`. Esse campo e opcional e serve a agente/automacao, nao muda a sintaxe publica.
+
+## Persistencia vendor-first
+
+O bloco `database` modela banco e recursos persistidos sem apagar as diferencas entre engines.
+
+Estrutura base:
+
+```sema
+database principal_postgres {
+  engine: postgres
+  consistency: forte
+  durability: alta
+  transaction_model: mvcc
+  query_model: sql
+}
+```
+
+Recursos canonicamente suportados:
+
+- `table`
+- `index`
+- `relationship`
+- `query`
+- `retention`
+- `lock`
+- `replication`
+- `collection`
+- `document`
+- `keyspace`
+- `stream`
+- `capabilities`
+
+Exemplo relacional:
+
+```sema
+database principal_postgres {
+  engine: postgres
+  schema: public
+  capabilities {
+    joins
+    views
+    foreign_keys
+  }
+  table pedidos {
+    entity: Pedido
+  }
+  relationship pedido_cliente {
+    from: Pedido
+    to: Cliente
+  }
+  query buscar_pedidos {
+    mode: sql
+  }
+}
+```
+
+Exemplo documental:
+
+```sema
+database principal_mongodb {
+  engine: mongodb
+  query_model: documento
+  collection pedidos {
+    collection: pedidos
+  }
+  document pedido_snapshot {
+    entity: PedidoSnapshot
+  }
+  query pipeline_pedido {
+    mode: pipeline
+  }
+}
+```
+
+Exemplo key-value:
+
+```sema
+database principal_redis {
+  engine: redis
+  query_model: chave_valor
+  keyspace cache_pedidos {
+    ttl: "300s"
+  }
+  stream eventos_pedido {
+    surface: fila
+  }
+}
+```
+
+## Compatibilidade declarada
+
+O IR de persistencia calcula compatibilidade por recurso com quatro estados:
+
+- `nativo`
+- `adaptado`
+- `parcial`
+- `invalido`
+
+Isso existe para deixar explicito quando um contrato esta pedindo de um banco algo que ele nao entrega do mesmo jeito.
+
+O mesmo principio vale para runtime de orquestracao. Superficies como `webhook`, `cron`, `worker`, `evento` e `fila` podem ser medidas contra familias como `n8n`, mas o contrato continua canonicamente modelado em Sema, sem rebaixar a linguagem para a sintaxe do adapter alvo.