@semacode/cli 1.5.16 → 1.5.17

package/docs/persistencia-vendor-first.md

@@ -0,0 +1,145 @@
+# Persistencia Vendor-First
+
+Sema 1.5.7 trata banco como superficie semantica de primeira classe. Isso significa assumir diferencas reais entre engines e coloca-las no contrato, no semantico, no 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.
+
+## 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,104 @@
+# 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.
+
+## Prompt-base
+
+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 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.
+
+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
+- 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 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:
+
+```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.10`, 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,410 @@
+# Sintaxe Canonica
+
+A Sema usa blocos declarativos previsiveis para reduzir ambiguidade no parser, na IR, no drift e no 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`
+- blocos declarativos podem aparecer aninhados quando o contrato exigir
+- `tests` usa blocos `caso`
+
+## Blocos de primeira classe
+
+- `module`
+- `use`
+- `database`
+- `type`
+- `entity`
+- `enum`
+- `state`
+- `book`
+- `work`
+- `part`
+- `chapter`
+- `section`
+- `scene`
+- `character`
+- `arc`
+- `audience`
+- `thesis`
+- `argument`
+- `claim`
+- `source`
+- `concept`
+- `example`
+- `voice`
+- `style_rule`
+- `lexicon`
+- `motif`
+- `canon`
+- `agent`
+- `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 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?`
+
+## Profiles Author e Agents
+
+O profile Author modela obra autoral, nao apenas romance. Ele pode descrever ficcao, nao-ficcao, livro tecnico, ensaio, manual, biografia, pesquisa narrada, curso em formato de livro ou manifesto. A ideia e governar intencao, publico, promessa, voz, estrutura, argumentos, fontes, continuidade e regras de estilo.
+
+Blocos Author suportados:
+
+- `book` ou `work`: obra inteira
+- `part`, `chapter`, `section`: estrutura editorial
+- `scene`, `character`, `arc`: narrativa quando a obra tiver ficcao ou relato
+- `audience`, `thesis`, `argument`, `claim`, `source`, `concept`, `example`: nao-ficcao, ensino, pesquisa e argumentacao
+- `voice`, `style_rule`, `lexicon`, `motif`, `canon`: voz, vocabulario, repeticoes, proibicoes e continuidade
+
+`style_rule` aceita subblocos livres como `proibido`, `evitar`, `ecos`, `preferir`, `require` e `tolerancia`. Isso cobre frases cliches, muletas, ecos repetidos e limites de repeticao sem prender a linguagem a um genero literario.
+
+Todo modulo com blocos Author tambem recebe no IR a regra sintetica `regras_gerais_author`. Ela aplica automaticamente o piso editorial geral: mostrar por evidencia, causa e consequencia, cena com dupla funcao, exposicao com atrito, dialogo com subtexto, final sem slogan, morte com peso estrutural, especificidade sensorial, voz distinta e anti-cliche adaptativa. Regras locais da obra podem ser mais fortes, mas nao devem apagar esse piso.
+
+Quando a obra declara um tema sensivel ou factual, como `autismo`, `saude`, `diagnostico`, `neurodiversidade`, `educacao inclusiva`, `juridico` ou `financeiro`, o contrato deixa de ser apenas orientativo. A validacao exige `book/work`, `audience`, `claim`, `source`, `style_rule`, `agent` e um `flow` chamando esse agent. Claims sensiveis precisam declarar `source/fonte/evidencia` e `confidence/confianca`.
+
+```sema
+module livro.tecnico.ia {
+  work protocolo_ia {
+    titulo: "Sistemas para IA"
+    proposito: "ensinar governanca de agentes"
+    tipo: nao_ficcao
+  }
+
+  audience devs {
+    nivel: intermediario
+    promessa: "sair com um protocolo aplicavel"
+  }
+
+  claim contratos_reduzem_adivinhacao {
+    source: pesquisa_interna
+    confidence: media
+  }
+
+  voice didatica {
+    tom: claro
+    ritmo: progressivo
+  }
+
+  style_rule anti_texto_raso {
+    proibido {
+      frase: "de alguma forma"
+      cliche: "o tempo parecia parar"
+    }
+    ecos {
+      palavra: "eco"
+    }
+    tolerancia {
+      max_repeticao_palavra_por_trecho: 2
+    }
+  }
+
+  agent revisor_estilo {
+    role: editor_author
+    goal: cortar_cliche_e_eco
+    tools {
+      ler_contrato
+      analisar_trecho
+    }
+    memory {
+      canon
+      style_rule
+    }
+    policy {
+      nao_reescrever_sem_aprovacao
+      citar_trechos_afetados
+    }
+  }
+
+  flow revisar_secao {
+    trecho: Texto
+    etapa estilo usa revisor_estilo com trecho = trecho
+  }
+}
+```
+
+`agent` e bloco de primeira classe. Um agent precisa declarar ao menos `role`/`goal`, `tools` e `policy`; `memory` gera aviso quando ausente, porque agente sem memoria declarada tende a improvisar contexto.
+
+Exemplo de obra sensivel:
+
+```sema
+module livro.autismo {
+  work guia_autismo {
+    titulo: "Autismo sem reducionismo"
+    proposito: "orientar familias sem substituir avaliacao clinica"
+    tema: autismo
+    sensivel: verdadeiro
+  }
+
+  audience familias_e_educadores {
+    publico: pais_educadores_pessoas_autistas
+    limites: "nao substitui avaliacao clinica"
+  }
+
+  claim autismo_e_espectro {
+    texto: "autismo e um espectro com manifestacoes variadas"
+    source: dsm5_tr
+    confidence: alta
+  }
+
+  source dsm5_tr {
+    tipo: referencia_clinica
+    confianca: alta
+  }
+
+  style_rule linguagem_respeitosa {
+    proibido {
+      generalizacao: "todo autista"
+      infantilizacao: "anjinho especial"
+      promessa: "cura garantida"
+    }
+    evitar {
+      frase: "superar o autismo"
+    }
+  }
+
+  agent checador_sensibilidade {
+    role: revisor_sensibilidade
+    goal: checar_fontes_linguagem_e_generalizacoes
+    tools {
+      ler_contrato
+      verificar_claim
+      revisar_trecho
+    }
+    memory {
+      source
+      style_rule
+      audience
+    }
+    policy {
+      nao_diagnosticar
+      nao_prometer_tratamento
+      citar_trechos_afetados
+    }
+  }
+
+  flow revisar_capitulo {
+    trecho: Texto
+    etapa sensibilidade usa checador_sensibilidade com trecho = trecho
+  }
+}
+```
+
+## 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.
+
+## Interop e implementacao externa
+
+`use` e `impl` aceitam origens de codigo vivo quando o contrato precisa rastrear runtime real. As origens semanticas suportadas sao:
+
+- `ts`
+- `py`
+- `dart`
+- `lua`
+- `php`
+- `cs`
+- `java`
+- `go`
+- `rust`
+- `cpp`
+
+Exemplo com Lua:
+
+```sema
+module app.runtime {
+  use lua src.runtime
+
+  task processar_snapshot {
+    input {
+      payload: Json required
+    }
+    output {
+      resultado: Json
+    }
+    impl {
+      lua: src.runtime.RuntimeBridge.processSnapshot
+    }
+    guarantees {
+      resultado existe
+    }
+  }
+}
+```
+
+Para Lua, o `drift` resolve funcoes declaradas como `function nome(...)`, `local function nome(...)`, `function Tabela.metodo(...)`, `function Tabela:metodo(...)` e atribuicoes `Tabela.metodo = function(...)`. A forma com `:` e normalizada para ponto no contrato.
+
+Exemplo com PHP:
+
+```sema
+module app.php {
+  use php App.Http.Controllers.UserController
+
+  task criar_usuario {
+    input {
+      payload: Json required
+    }
+    output {
+      resultado: Json
+    }
+    impl {
+      php: App.Http.Controllers.UserController.store
+    }
+    guarantees {
+      resultado existe
+    }
+  }
+}
+```
+
+Para PHP, o `drift` resolve namespaces, classes, traits, interfaces, enums, metodos, funcoes, closures atribuidas, rotas Laravel/Slim (`Route::get`, `Route::post`, `$app->get`) e atributos HTTP no estilo Symfony/PHP 8 (`#[Route]`, `#[Get]`, `#[Post]`). `Route::resource` e `Route::apiResource` sao expandidos para acoes REST canonicas.