@semacode/cli 1.5.7 → 1.5.9

package/docs/deploy.md

@@ -0,0 +1,70 @@
+# Deploy
+
+Este runbook governa a publicacao publica da Sema: CLI, MCP, VSIX, instaladores e release assets.
+
+## Pre-condicoes
+
+- `sema resumo` executado no projeto antes da mudanca.
+- `sema inspecionar contratos/sema/governanca_ia.sema --json` executado para confirmar o contrato relacionado.
+- `sema drift contratos/sema/governanca_ia.sema --escopo modulo --json` sem diagnosticos bloqueantes.
+- `sema docs-impacto --intencao "<release>" --criar-ausentes --json` executado e todos os docs obrigatorios lidos.
+- `npm whoami` autenticado com uma conta que pode publicar `@semacode/cli` e `@semacode/mcp`.
+- `gh auth status` autenticado com permissao de push e release em `gerlanss/Sema`.
+- Workspace revisado para nao incluir lixo local, caches ou artefatos temporarios fora de `.tmp/`.
+
+## Sequencia segura
+
+1. Escolha uma versao que ainda nao exista no NPM.
+2. Atualize `package.json`, workspaces, lockfiles, changelog e docs antes de empacotar.
+3. Rode `npm run build`.
+4. Rode os testes focados e checagens de release.
+5. Rode `npm run release:preparar-publica` para gerar `.tmp/release-assets`.
+6. Publique NPM com `npm run release:publicar-npm`.
+7. Instale a CLI e o MCP publicados para smoke test.
+8. Empacote e instale a VSIX localmente para smoke test da extensao.
+9. Rode `sema finalizar-mudanca` com as docs lidas antes de concluir.
+10. Commit, push, tag e GitHub Release com os assets gerados.
+
+## Validacao minima
+
+```bash
+npm run build
+npm run format:check
+npm run status:check
+node --import tsx --test --test-name-pattern "docs operacionais|ajuda de ia|mcp cli responde" testes/integracao/cli-json-e-editor.test.ts
+sema validar contratos/sema/governanca_ia.sema --json
+sema drift contratos/sema/governanca_ia.sema --escopo modulo --json
+```
+
+Depois de publicar:
+
+```bash
+npm view @semacode/cli version
+npm view @semacode/mcp version
+npm install -g @semacode/cli@<versao>
+npm install -g @semacode/mcp@<versao>
+sema --version
+sema docs-impacto --intencao "smoke release" --json
+sema-mcp --help
+```
+
+## Release assets
+
+`npm run release:preparar-publica` deve gerar:
+
+- `sema-cli-<versao>.tgz`
+- `sema-cli-latest.tgz`
+- `sema-language-tools-<versao>.vsix`
+- `sema-language-tools-latest.vsix`
+- `install-sema.sh`
+- `install-sema.ps1`
+- `SHA256SUMS.txt`
+- `release-notes.md`
+
+## Sinais de parada
+
+- NPM ja tem a versao escolhida.
+- `npm whoami` falha.
+- `gh auth status` falha.
+- `sema validar`, `sema drift`, build ou testes falham.
+- `release:preparar-publica` encontra versoes desalinhadas entre root, CLI, MCP e extensao.

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.9 -WithVSCode -WithMcp
+```
+
+No shell:
+
+```bash
+SEMA_VERSION=1.5.9 ./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.9`.
+
+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/instalacao-e-primeiro-uso.md

@@ -16,6 +16,7 @@ Instalacao principal:
 npm install -g @semacode/cli
 sema --help
 sema doctor
+sema docs-impacto --intencao "alterar projeto" --json
 ```
 
 Instalacao por release:
@@ -46,6 +47,8 @@ Ou sem instalar:
 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:

package/docs/integracao-com-ia.md

@@ -58,6 +58,26 @@ 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
 
@@ -75,3 +95,5 @@ Ferramentas mais uteis no fluxo de mudanca:
 - `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.

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/node_modules/@sema/gerador-css/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/gerador-css",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/node_modules/@sema/gerador-dart/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/gerador-dart",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/node_modules/@sema/gerador-html/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/gerador-html",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/node_modules/@sema/gerador-javascript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/gerador-javascript",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/node_modules/@sema/gerador-lua/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/gerador-lua",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/node_modules/@sema/gerador-python/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/gerador-python",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/node_modules/@sema/gerador-typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/gerador-typescript",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/node_modules/@sema/nucleo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/nucleo",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/node_modules/@sema/padroes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema/padroes",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semacode/cli",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "description": "CLI da Sema para validar contratos, medir drift e governar a navegacao operacional de agentes sobre software vivo, incluindo persistencia vendor-first para bancos reais.",
   "type": "module",
   "icon": "logo.png",
@@ -49,15 +49,15 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@sema/nucleo": "1.5.7",
-    "@sema/gerador-dart": "1.5.7",
-    "@sema/gerador-lua": "1.5.7",
-    "@sema/gerador-python": "1.5.7",
-    "@sema/gerador-typescript": "1.5.7",
-    "@sema/gerador-javascript": "1.5.7",
-    "@sema/gerador-html": "1.5.7",
-    "@sema/gerador-css": "1.5.7",
-    "@sema/padroes": "1.5.7",
+    "@sema/nucleo": "1.5.9",
+    "@sema/gerador-dart": "1.5.9",
+    "@sema/gerador-lua": "1.5.9",
+    "@sema/gerador-python": "1.5.9",
+    "@sema/gerador-typescript": "1.5.9",
+    "@sema/gerador-javascript": "1.5.9",
+    "@sema/gerador-html": "1.5.9",
+    "@sema/gerador-css": "1.5.9",
+    "@sema/padroes": "1.5.9",
     "typescript": "^5.8.3"
   },
   "bundledDependencies": [