@semacode/cli 1.5.14 → 1.5.16

package/docs/persistencia-vendor-first.md

@@ -1,145 +0,0 @@
-# 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

@@ -1,104 +0,0 @@
-# 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

@@ -1,47 +0,0 @@
-# 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

@@ -1,410 +0,0 @@
-# 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.