@semacode/cli 1.5.11 → 1.5.16

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

@@ -1,112 +0,0 @@
-# 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
-sema docs-impacto --intencao "alterar projeto" --json
-```
-
-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
-```
-
-As ferramentas MCP incluem `sema_docs_impacto` e `sema_finalizar_mudanca` para obrigar agentes a ler e atualizar docs relacionadas antes de concluir alteracoes.
-
-## Instaladores oficiais
-
-Linux ou macOS:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/gerlanss/Sema/main/install-sema.sh | bash
-curl -fsSL https://raw.githubusercontent.com/gerlanss/Sema/main/install-sema.sh | bash -s -- --with-vscode --with-mcp
-```
-
-Windows PowerShell:
-
-```powershell
-Invoke-WebRequest -Uri https://raw.githubusercontent.com/gerlanss/Sema/main/install-sema.ps1 -OutFile install-sema.ps1
-.\install-sema.ps1 -WithVSCode -WithMcp
-```
-
-Se quiser uma tag especifica, troque `main` pela versao desejada.
-
-## 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 --escopo modulo --json
-sema impacto contratos/pedidos.sema --alvo pedido_id --mudanca "trocar pedido_id por pedido_uuid" --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

@@ -1,101 +0,0 @@
-# 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"]
-    }
-  }
-}
-```
-
-Ferramentas mais uteis no fluxo de mudanca:
-
-- `sema_drift` para medir coerencia viva
-- `sema_impacto` para dizer o que tocar
-- `sema_renomear_semantico` para guiar troca de nomes sem misturar payload antigo e novo
-- `sema_docs_impacto` para obrigar leitura das docs relacionadas antes de agir
-- `sema_finalizar_mudanca` para bloquear conclusao sem leitura documental comprovada
-
-As ferramentas MCP usam a CLI como backend operacional. Portanto, suporte de linguagem como Lua em `use`, `impl`, IR, `drift` e importacao fica disponivel no MCP quando `@semacode/cli` e `@semacode/mcp` estao na mesma linha publica.
-
-## Portao documental
-
-Antes de editar ou executar operacao sensivel, declare a intencao:
-
-```bash
-sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
-```
-
-Leia todos os itens em `leituraObrigatoria`. Se `docsAusentes` vier preenchido, crie ou complete os documentos antes da acao.
-
-Antes de concluir:
-
-```bash
-sema finalizar-mudanca --intencao "fazer deploy" --doc-lida docs/deploy.md --json
-```
-
-Se houver diagnostico de severidade 4+, a IA nao deve finalizar a mudanca.
-
-## 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`
-- `docs/mcp.md`
-- `docs/documentacao.md`

package/docs/mcp.md

@@ -1,53 +0,0 @@
-# MCP
-
-O MCP da Sema e a porta de entrada para agentes que precisam obedecer contrato, ler contexto certo e fechar mudanca com verificacao rastreavel.
-
-## Fluxo obrigatorio para agentes
-
-Antes de uma acao operacional, a IA deve declarar a intencao e chamar:
-
-```bash
-sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
-```
-
-Via MCP, use `sema_docs_impacto` com a mesma intencao. A resposta contem `leituraObrigatoria` com caminhos, motivos e conteudo dos documentos existentes. Se algum documento obrigatorio estiver ausente, o resultado vem com bloqueio de severidade 4.
-
-Antes de concluir, a IA deve comprovar leitura:
-
-```bash
-sema finalizar-mudanca --intencao "fazer deploy" --doc-lida docs/deploy.md --json
-```
-
-Via MCP, use `sema_finalizar_mudanca`.
-
-## Ferramentas de documentacao
-
-- `sema_docs_impacto`: resolve docs obrigatorias por intencao, arquivos alvo e categoria inferida.
-- `sema_finalizar_mudanca`: bloqueia conclusao sem docs lidas ou docs ausentes.
-
-## Quando criar docs
-
-Se a intencao exige um runbook e ele nao existe, rode `sema_docs_impacto` com `criar_ausentes: true`. Exemplos:
-
-- deploy: cria `docs/deploy.md`, `docs/env.md` e `docs/rollback.md`.
-- rota/API: cria `docs/api.md`.
-- auth: cria `docs/auth.md` e `docs/seguranca.md`.
-- banco: cria `docs/database.md`.
-- MCP: cria `docs/mcp.md`.
-- extensao: cria `docs/extensao-vscode.md`.
-
-O documento criado e um ponto de partida. A IA ainda deve preencher detalhes reais do projeto antes de executar a acao.
-
-## Regra de conclusao
-
-Uma mudanca nao deve ser considerada concluida enquanto `sema_finalizar_mudanca` retornar diagnostico de severidade 4 ou maior. Isso inclui:
-
-- documento obrigatorio ausente
-- leitura obrigatoria nao comprovada
-- runbook criado mas ainda nao revisado para a operacao real
-
-## Relacao com contratos
-
-Essas ferramentas nao substituem `sema_resumo`, `sema_inspecionar`, `sema_drift` ou `sema_validar`. Elas adicionam o portao documental: a IA descobre o que ler e o que documentar antes de agir.
-
-O MCP acompanha a semantica entregue pela CLI. Quando a CLI aceita uma origem viva, como Lua em `use`, `impl`, IR, `drift` e `sema importar`, a ferramenta MCP correspondente passa a operar esse contrato desde que CLI e MCP estejam na mesma versao.

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

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

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.