@semacode/cli 1.5.16 → 1.5.18

package/docs/documentacao.md

@@ -0,0 +1,63 @@
+# Governanca de Documentacao
+
+A Sema trata documentacao como parte da mudanca, nao como pos-escrito simpatico para alguem lembrar depois.
+
+## Regra principal
+
+Toda IA deve resolver documentacao obrigatoria antes de editar contrato, codigo, configuracao ou executar operacoes como deploy.
+
+```bash
+sema docs-impacto --intencao "criar rota de pagamento" --arquivo contratos/pagamento.sema --json
+```
+
+Se o comando apontar docs ausentes, crie ou preencha essas docs antes da acao. Para criar runbooks base:
+
+```bash
+sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
+```
+
+## Leitura obrigatoria
+
+O resultado de `docs-impacto` traz:
+
+- `leituraObrigatoria`: docs, readmes e contratos que devem ser lidos.
+- `docsAusentes`: docs que bloqueiam a acao.
+- `docsCriadas`: docs criadas automaticamente quando autorizado.
+- `bloqueios`: diagnosticos de severidade 4.
+
+O conteudo dos documentos existentes vem na resposta para que o agente realmente leia o material antes de agir.
+
+## Finalizacao
+
+Antes de responder que terminou, a IA deve chamar:
+
+```bash
+sema finalizar-mudanca --intencao "criar rota de pagamento" --doc-lida README.md --doc-lida docs/api.md --json
+```
+
+Se faltar leitura ou documentacao, a conclusao deve ser bloqueada.
+
+## Docs que podem nascer automaticamente
+
+O Sema cria runbooks base para categorias operacionais:
+
+- `docs/deploy.md`
+- `docs/env.md`
+- `docs/rollback.md`
+- `docs/api.md`
+- `docs/auth.md`
+- `docs/seguranca.md`
+- `docs/database.md`
+- `docs/frontend.md`
+- `docs/testes.md`
+- `docs/mcp.md`
+- `docs/documentacao.md`
+- `docs/extensao-vscode.md`
+
+Esses arquivos sao esqueletos seguros. Eles devem ser completados com detalhes reais do projeto quando a operacao exigir.
+
+## O que nao fazer
+
+- Nao concluir uma mudanca sem rodar o portao documental.
+- Nao usar doc criada automaticamente como evidencia final se ela ainda esta generica.
+- Nao editar codigo sem contrato e sem leitura das docs relacionadas.

package/docs/env.md

@@ -0,0 +1,56 @@
+# Env
+
+Ambiente necessario para publicar a Sema.
+
+## Ferramentas
+
+- Node.js LTS com `npm`.
+- Git com acesso push ao remoto `origin`.
+- GitHub CLI (`gh`) autenticado.
+- VS Code CLI (`code`) para instalar a VSIX localmente.
+- PowerShell no Windows.
+
+## Variaveis suportadas pelos instaladores
+
+- `SEMA_REPO`: repositorio GitHub usado para baixar assets. Padrao: `gerlanss/Sema`.
+- `SEMA_NPM_PACKAGE`: pacote da CLI. Padrao: `@semacode/cli`.
+- `SEMA_MCP_NPM_PACKAGE`: pacote do MCP. Padrao: `@semacode/mcp`.
+- `SEMA_VERSION`: versao usada pelo `install-sema.sh`. Padrao: `latest`.
+
+No PowerShell, o instalador recebe a versao por parametro:
+
+```powershell
+.\install-sema.ps1 -Version 1.5.18 -WithVSCode -WithMcp
+```
+
+No shell:
+
+```bash
+SEMA_VERSION=1.5.18 ./install-sema.sh --with-vscode --with-mcp
+```
+
+## Credenciais
+
+- NPM deve estar logado antes de publicar: `npm whoami`.
+- GitHub CLI deve estar logado antes de criar release: `gh auth status`.
+- Nunca registre tokens em docs, logs ou release notes.
+
+## Registro NPM
+
+Os pacotes publicos sao:
+
+- `@semacode/cli`
+- `@semacode/mcp`
+
+Antes de publicar, confira:
+
+```bash
+npm view @semacode/cli version
+npm view @semacode/mcp version
+```
+
+## GitHub Release
+
+O tag publico deve seguir `v<versao>`, por exemplo `v1.5.18`.
+
+Os assets ficam em `.tmp/release-assets` e sao derivados dos scripts versionados no repositorio.

package/docs/extensao-vscode.md

@@ -0,0 +1,45 @@
+# Extensao VS Code
+
+Runbook da extensao `Sema Language Tools`.
+
+## Arquivos principais
+
+- `pacotes/editor-vscode/package.json`
+- `pacotes/editor-vscode/extension.js`
+- `pacotes/editor-vscode/server.js`
+- `pacotes/editor-vscode/README.md`
+- `pacotes/editor-vscode/CHANGELOG.md`
+
+## Empacotar
+
+```bash
+npm run extensao:empacotar
+```
+
+O pacote versionado deve aparecer em `.tmp/editor-vscode/sema-language-tools-<versao>.vsix`.
+
+## Instalar localmente
+
+```bash
+npm run extensao:instalar-local
+```
+
+Ou:
+
+```bash
+code --install-extension .tmp/editor-vscode/sema-language-tools-<versao>.vsix --force
+```
+
+## Smoke test
+
+1. Abra um projeto com `.sema`.
+2. Confirme que o Language Server inicia sem crash.
+3. Rode `Sema: Diagnosticar CLI`.
+4. Rode `Sema: Sincronizar EntryPoints IA do Projeto`.
+5. Abra um `.sema` e confirme diagnosticos, highlight e formatação.
+
+## Cuidados
+
+- O `extension.js` deve apontar o LSP para `server.js`.
+- A extensao embute instrucoes de IA; atualize a lista de ferramentas MCP quando novos comandos forem adicionados.
+- A versao da extensao deve bater com a versao publica preparada por `release:preparar-publica`.

package/docs/fluxo-pratico-ia-sema.md

@@ -0,0 +1,181 @@
+# 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.
+
+O ponto central: Sema nao e texto para agradar humano. E contrato semantico IA-first. Humanos autorizam e revisam; a IA consome o contrato para decidir o proximo movimento.
+
+## Fluxo curto
+
+1. ler contexto do projeto
+2. identificar a capacidade da IA
+3. identificar o modulo alvo
+4. consultar o menor artefato semantico suficiente
+5. editar
+6. formatar
+7. validar
+8. 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. Escolher a faixa de capacidade
+
+Antes de despejar contexto na IA, escolha o que ela aguenta:
+
+- IA pequena ou gratuita: `sema resumo --micro` e `briefing.min.json`
+- IA media: `sema resumo --curto`, `briefing.min.json` e `drift.json`
+- IA grande: `contexto-ia`, `briefing.json`, `drift.json`, `ir.json` e `ast.json`
+
+### Etapa 3. 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 4. Consultar AST e IR quando fizer sentido
+
+Antes de alterar, a IA deve executar:
+
+```bash
+sema resumo caminho/arquivo.sema --curto --para mudanca
+sema ast caminho/arquivo.sema --json
+sema ir caminho/arquivo.sema --json
+```
+
+Objetivo:
+
+- ver a forma sintatica quando a capacidade aguentar
+- ver a forma semantica resolvida quando a capacidade aguentar
+- evitar interpretar errado o contrato
+
+### Etapa 5. 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
+- usar blocos existentes como `auth`, `authz`, `dados`, `audit`, `forbidden`, `execucao`, `use`, `state` e `enum` antes de propor sintaxe nova
+- evitar teste fraco em task sensivel; `expect { sucesso: verdadeiro }` sozinho nao prova semantica operacional
+
+### Etapa 6. Formatar
+
+Depois da edicao:
+
+```bash
+sema formatar caminho/arquivo.sema
+sema formatar caminho/arquivo.sema --check
+```
+
+Se `--check` falhar, o trabalho ainda nao esta pronto.
+
+### Etapa 7. Validar e diagnosticar
+
+Depois da formatacao:
+
+```bash
+sema validar caminho/arquivo.sema --json
+sema 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 7.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
+sema 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 8. Verificar
+
+No fechamento:
+
+```bash
+sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
+```
+
+## Fluxo minimo para automacao
+
+Se voce quiser o menor fluxo aceitavel para uma IA pequena:
+
+```bash
+sema resumo caminho/arquivo.sema --micro --para mudanca
+sema formatar caminho/arquivo.sema
+sema 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
+sema ir caminho/arquivo.sema --json
+sema formatar caminho/arquivo.sema
+sema validar caminho/arquivo.sema --json
+sema 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 placeholders de arquivo e pasta, nao caminhos do monorepo da Sema. A IA deve adaptar isso ao projeto atual e continuar tratando `sema` como interface publica principal.

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

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

@@ -0,0 +1,103 @@
+# Integracao com IA
+
+Sema foi feita para IA operar software vivo com menos adivinhacao. O consumidor principal nao e o humano lendo arquivo bonito; e o agente decidindo o que pode tocar, que efeito vai causar e como validar antes de mexer no codigo vivo.
+
+Humanos entram como autores, revisores e aprovadores do contrato. A ponte da Sema e da intencao operacional para um formato que IA consegue consumir sem transformar contexto em chute.
+
+## 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
+
+## 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 humanos como donos/aprovadores e agentes como consumidores primarios do contrato
+- 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 task sensivel, teste que valida apenas `sucesso` e fraco; inclua output, erro esperado ou garantia observavel
+- 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

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