@semacode/cli 1.5.29 → 1.5.30

package/docs/mcp.md

@@ -1,292 +0,0 @@
-# Private MCP
-
-## English
-
-The Sema MCP is a private/commercial remote surface for agents that must obey contracts, read the right context, and close changes with traceable verification. It is not shipped in the public npm package and must not be documented as an open server package.
-
-Use OAuth for browser-based clients such as ChatGPT and Lovable when available. Use bearer keys only for clients that need that fallback. Fixed server tokens must not be the primary path for web apps.
-
-## Português
-
-O MCP da Sema é uma superfície remota privada/comercial para agentes que precisam obedecer contrato, ler contexto certo e fechar mudança com verificação rastreável. Ele não acompanha a release pública, não é publicado como pacote npm aberto e não deve ser documentado como pacote aberto de servidor.
-
-Use OAuth para clientes baseados em navegador, como ChatGPT e Lovable, quando disponível. Use chaves bearer apenas para clientes que precisam desse fallback. Tokens fixos de servidor não devem ser o caminho principal em apps web.
-
-## Español
-
-El MCP de Sema es una superficie remota privada/comercial para agentes que deben obedecer contratos, leer el contexto correcto y cerrar cambios con verificación trazable. No se distribuye en el paquete público de npm y no debe documentarse como paquete abierto de servidor.
-
-Usa OAuth para clientes basados en navegador, como ChatGPT y Lovable, cuando esté disponible. Usa claves bearer solo para clientes que necesitan ese fallback. Los tokens fijos de servidor no deben ser el camino principal en apps web.
-
-## Referência Operacional
-
-O repositório público documenta apenas o contrato de uso do serviço. A implementacao fica no pacote privado mantido fora deste monorepo.
-
-## Modelo de distribuição
-
-- Público: CLI, núcleo, geradores, contratos, exemplos, docs e extensao VS Code.
-- Privado: servidor MCP, OAuth, bearer, roots permitidas, deploy remoto, healthcheck e ferramentas remotas.
-- Consumo externo: ChatGPT, Codex, n8n, backends e outros agentes acessam um endpoint HTTPS `/mcp` operado por quem controla o serviço.
-
-Não use mais `npm install -g @semacode/mcp` nem `npx -y @semacode/mcp` em documentação pública. Esses caminhos eram validos enquanto o MCP era distribuido como pacote aberto; agora a integração correta e via URL remota autorizada.
-
-## Endpoint remoto
-
-Para ChatGPT Apps ou conectores baseados em MCP, a URL deve apontar para:
-
-```text
-https://sema.exemplo.com/mcp
-```
-
-Para clientes legados que ainda pedem SSE:
-
-```text
-https://sema.exemplo.com/sse
-```
-
-Endpoints esperados do serviço remoto:
-
-- `GET /healthz`: healthcheck sem segredo para proxy e deploy.
-- `GET /logo.png`: logo pública do servidor MCP.
-- `POST /mcp`: MCP Streamable HTTP.
-- `GET /mcp` e `DELETE /mcp`: continuidade/fechamento de sessão quando o cliente usa `mcp-session-id`.
-- `GET /sse` e `POST /message`: SSE legado.
-- `GET /.well-known/oauth-protected-resource`: metadata OAuth para recursos protegidos.
-- `GET /.well-known/oauth-authorization-server`: metadata do authorization server.
-- `POST /oauth/register`: dynamic client registration.
-- `GET|POST /oauth/authorize`: autorizacao com passcode.
-- `POST /oauth/token`: emissao e refresh de tokens.
-
-## ChatGPT
-
-No ChatGPT normal, em **Settings -> Apps & Connectors -> Advanced settings -> Create**:
-
-- Icone: PNG quadrado, mínimo `128x128`, maximo `10 KB`.
-- Nome: `Sema`.
-- Descricao: `Contrato semantico IA-first para agentes validarem, inspecionarem e operarem software vivo com drift, impacto e garantias.`
-- URL do servidor MCP: `https://sema.exemplo.com/mcp`.
-- Autenticação: `OAuth`.
-
-O ChatGPT abre a página de autorizacao do Sema, o operador digita o passcode privado e o servidor emite tokens proprios para o app. Nunca coloque bearer, OAuth secret ou passcode em README, AGENTS, release notes, prints ou logs.
-
-## Regra Zero Do MCP
-
-O MCP deve deixar claro, em toda orientacao operacional, que contrato vem antes da ação. Antes de código, deploy, geracao, revisão, texto Author, workflow, ops, game, legal, research ou qualquer outro profile, a IA precisa criar, editar ou remover o contrato `.sema` aplicavel.
-
-Se não existe contrato, a próxima ação e criar contrato. Se a intenção muda comportamento, a próxima ação e editar contrato. Se a funcionalidade deixa de existir, a próxima ação e remover ou aposentar o contrato. Só depois disso entram drift, impacto, código vivo, artefatos, deploy ou texto gerado.
-
-Essa regra vale para Software, Author, Workflow, Ops, Game, Legal, Research e qualquer profile futuro. Um MCP que permite agir sem ciclo de contrato virou autocomplete com cracha, não Sema.
-
-## Codex É Outros Agentes
-
-Para ambientes que aceitam MCP HTTP, configure o endpoint remoto e armazene a chave comercial `sema_mcp_*` no mecanismo de segredo do cliente. Essa chave identifica o workspace/projeto e alimenta o billing; ela nao e um token fixo global do servidor.
-
-No Windows, a CLI pode gravar a chave como variavel do usuario sem colocar o segredo em argumento de processo:
-
-```powershell
-Get-Clipboard | sema mcp-instalar-chave --stdin --json
-```
-
-No VS Code oficial, use o comando `Sema: Instalar Chave MCP` e cole a chave gerada no painel. A extensao chama a CLI por stdin, grava `SEMA_MCP_AUTH_TOKEN` no usuario e orienta reabrir o cliente.
-
-Exemplo de `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.sema]
-url = "https://sema.exemplo.com/mcp"
-bearer_token_env_var = "SEMA_MCP_AUTH_TOKEN"
-tool_timeout_sec = 90
-```
-
-Para ambientes sem suporte a bearer do cliente, use OAuth quando disponivel. OAuth nao deve reutilizar uma chave fixa de servidor.
-
-## IDE Local Vs App Remoto
-
-O MCP só deve ler arquivos do ambiente onde ele roda.
-
-- Em IDE/plugin com workspace local, o fluxo preferencial e enviar um snapshot tipado para `sema_contratos_sincronizar`: `contratos`, `arquivos_codigo`, `documentacao` e `indice`. Quando a tarefa precisar verificar implementacao, envie código selecionado, nunca o projeto inteiro.
-- Em ChatGPT/app remoto, o MCP roda no servidor e só enxerga roots do servidor, como `/srv/sema/projetos/...`. Caminho local de IDE não deve cair silenciosamente para outro projeto.
-- Toda chamada operacional deve enviar `projeto` com um caminho existente no servidor ou com o caminho retornado pelo espelho de contratos. Em HTTP remoto, `projeto` vazio ou `.` deve falhar com `workspace_atual_nao_informado`; cair em `/srv/sema/projetos/Sema` seria validar o repositório errado.
-- Quando o workspace não vier no contexto, a IA deve pedir ou usar a sincronizacao de contratos remotos e código selecionado. MCP local/stdio e opcional e deve ser reservado para drift contra código vivo completo.
-- Quando o arquivo veio de upload, anexo ou sandbox do chat, use `conteudo` inline.
-- Para `sema_drift`, `escopo = arquivo` ou `escopo = modulo` exige alvo explícito. Envie `arquivo` ou `contrato_alvo` com o `.sema` alvo dentro do `projeto`; se enviar apenas o diretorio do projeto, o MCP remoto deve retornar `contrato_alvo_nao_informado`. Use `escopo = projeto` somente quando a auditoria global for intencional.
-
-Se uma IA pedir `C:\GitHub\Gestech` para um MCP remoto Linux, o servidor deve responder erro claro de caminho local inacessivel e orientar sincronizar contratos e código selecionado com `sema_contratos_sincronizar`. MCP local/stdio só entra quando a tarefa exige ler código local completo.
-
-Exemplo de drift remoto focado:
-
-```json
-{
-  "projeto": "/srv/sema/projetos/_contratos_remotos/github-gestech-0e2eb48843",
-  "arquivo": "contratos/promocoes.sema",
-  "escopo": "modulo",
-  "json": true
-}
-```
-
-## Ferramentas Expostas
-
-A lista concreta depende da versão privada implantada, mas o contrato atual espera:
-
-- `sema_mcp_doctor`
-- `sema_resumo`
-- `sema_contratos_sincronizar`
-- `sema_contrato_salvar`
-- `sema_contrato_remover`
-- `sema_listar_contratos`
-- `sema_ler_contrato`
-- `sema_validar`
-- `sema_drift`
-- `sema_impacto`
-- `sema_renomear_semantico`
-- `sema_inspecionar`
-- `sema_ir`
-- `sema_verificar`
-- `sema_contexto_ia`
-- `sema_prompt_ia`
-- `sema_author_iniciar`
-- `sema_author_validar`
-- `sema_author_briefing`
-- `sema_author_revisar_cliches`
-- `sema_profile_validar`
-- `sema_sync_ai_entrypoints`
-- `sema_instalar_exemplos`
-- `sema_docs_impacto`
-- `sema_finalizar_mudanca`
-
-O doctor operacional do MCP privado fica no backlog do serviço comercial. Quando existir, ele deve retornar versão do MCP, versão da CLI, transporte, `cwd` do processo, `cwd` efetivo, raiz detectada, roots permitidas, endpoints e marcadores do projeto sem expor tokens, secrets ou passcodes.
-
-## Arquivos Enviados No ChatGPT
-
-O MCP remoto roda no servidor e não le caminhos do sandbox do ChatGPT como `/mnt/data/pedido.sema`. Para esses casos, ferramentas de contrato devem aceitar `conteudo` inline:
-
-```json
-{
-  "conteudo": "module exemplo { ... }",
-  "nome_arquivo": "pedido.sema"
-}
-```
-
-Use `conteudo` em `sema_validar`, `sema_ir`, `sema_inspecionar`, `sema_contexto_ia`, `sema_author_validar`, `sema_author_briefing` e `sema_author_revisar_cliches` quando o contrato vier de upload, anexo ou texto colado.
-
-Use `arquivo` apenas quando o caminho existir dentro das roots permitidas no servidor. Se uma IA enviar `/mnt/data/...`, o servidor deve orientar repetir a chamada usando `conteudo`.
-
-## Espelho De Contratos Da IDE
-
-Para IDEs e plugins, o MCP remoto não precisa ler o projeto inteiro para
-governar a mudanca. O cliente deve enviar um snapshot tipado:
-
-```json
-{
-  "projeto_id": "C:\\GitHub\\Gestech",
-  "nome_projeto": "Gestech",
-  "contratos": [
-    {
-      "caminho": "contratos/produtos_catalogo.sema",
-      "conteudo": "module ... { ... }"
-    }
-  ],
-  "arquivos_codigo": [
-    {
-      "caminho": "routes/produtos.py",
-      "conteudo": "def listar_produtos(...): ..."
-    },
-    {
-      "caminho": "tests/test_produtos.py",
-      "conteudo": "def test_listar_produtos(...): ..."
-    }
-  ],
-  "documentacao": [
-    {
-      "caminho": "AGENTS.md",
-      "tipo": "operacional",
-      "conteudo": "# Regras do projeto..."
-    },
-    {
-      "caminho": "docs/VPS_DEPLOY.md",
-      "tipo": "deploy",
-      "conteudo": "# Deploy..."
-    }
-  ],
-  "indice": [
-    {
-      "caminho": "routes/produtos.py",
-      "tipo": "codigo",
-      "hash": "sha256:...",
-      "mtime": "2026-05-16T12:00:00Z",
-      "resumo": "Rotas de produtos"
-    }
-  ]
-}
-```
-
-O servidor grava em uma pasta Linux dedicada contendo contratos, metadados
-mínimos e apenas os arquivos de código enviados. A resposta traz `projeto`;
-esse caminho deve ser usado nas proximas chamadas. Se o Sema criar, editar ou
-remover um contrato, a IDE deve trazer a alteracao de volta para o workspace
-local antes de qualquer código.
-
-O código enviado deve ser selecionado por criterio: arquivos citados em `impl`,
-`vinculos`, routes, effects, services/repos proximos e testes relacionados. O
-MCP deve bloquear `.env`, tokens, chaves, `node_modules`, `.git`, build/cache,
-uploads, dependências instaladas e snapshots de repo inteiro. Quando nenhum
-código for enviado, o Sema deve declarar `contratos_apenas` e trocar lacunas de
-implementacao por `implementacao_nao_enviada` ou
-`codigo_nao_verificado_neste_modo`. Quando código parcial for enviado, deve
-declarar `codigo_selecionado` e limitar a conclusóo ao snapshot.
-
-Documentação enviada deve ser operacional ou de negócio: `AGENTS.md`,
-`README.md`, docs do módulo mexido, notas de deploy quando a tarefa envolve
-VPS, runbooks em incidentes e exemplos Sema quando a IA estiver criando
-contrato. O índice deve conter mapa de arquivos relevantes, hashes, timestamps
-é resumo curto sem conteúdo sensível.
-
-Toda conclusóo precisa declarar sua fonte: `contrato`, `codigo`,
-`documentacao` ou `indice`. Exemplos de leitura: bloqueado pelo contrato;
-divergente do código; regra documentada mas sem contrato; documentação
-contradiz implementacao; escopo inferido pelo índice.
-
-`sema_author_revisar_cliches` opera como validador bloqueante: violacao de politica Author deve retornar `aprovado: false`, `bloqueado: true` e `sucesso: false`. Um contrato narrativo que não bloqueia drift, voz genérica ou tema sensível sem autorizacao não deve ser tratado como contrato.
-
-## Segurança Operacional
-
-O servidor privado deve rodar com:
-
-- HTTPS no reverse proxy.
-- Chave comercial bearer por request ou OAuth obrigatorio.
-- Passcode OAuth configurado para ChatGPT.
-- Roots restritas a uma pasta dedicada, por exemplo `/srv/sema/projetos`.
-- Logs sem tokens, passcodes, secrets ou conteúdo sensível desnecessário.
-- Rotacao imediata da chave comercial ou segredo OAuth se qualquer valor aparecer em terminal compartilhado, print, chat ou log.
-
-Nunca publique `/mcp` ou `/sse` sem autenticação e raiz restrita.
-
-## Fluxo Obrigatorio Para Agentes
-
-Antes de uma ação operacional, a IA deve declarar a intenção e resolver o contrato:
-
-1. `sema_resumo` para descobrir o estado do projeto.
-2. `sema_listar_contratos` e `sema_ler_contrato` quando disponiveis, ou `sema_inspecionar` no `.sema` mais próximo.
-3. Criar, editar ou remover o contrato aplicavel antes de tocar código, docs operacionais, deploy, texto Author, workflow, jogo, juridico, pesquisa ou ops.
-4. `sema_validar` no contrato alterado.
-5. `sema_drift`, `sema_impacto` ou gate de profile/Author conforme o tipo.
-
-Depois do ciclo de contrato, a IA deve chamar:
-
-```bash
-sema docs-impacto --intencao "fazer deploy" --criar-ausentes --json
-```
-
-Via MCP privado, use `sema_docs_impacto` com a mesma intenção. A resposta contem `leituraObrigatoria` com caminhos, motivos e conteúdo dos documentos existentes.
-
-Antes de concluir:
-
-```bash
-sema finalizar-mudanca --intencao "fazer deploy" --doc-lida docs/deploy.md --json
-```
-
-Via MCP privado, use `sema_finalizar_mudanca`.
-
-## Relação Com Contratos
-
-Essas ferramentas não substituem `sema_resumo`, `sema_inspecionar`, `sema_drift` ou `sema_validar`. Elas adicionam a camada remota privada para agentes fora da máquina local. O contrato continua sendo o portao: criar, editar ou remover contrato antes de qualquer ação e obrigatorio em todo tipo de Sema.

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

@@ -1,171 +0,0 @@
-# Pagamento Ponta a Ponta na Sema
-
-<!-- sema:i18n -->
-> EN: English first. The canonical operational body below may still be in Portuguese until full translation lands.
-> PT: Português depois, com acentos preservados.
-> ES: Español al final; não traduza comandos, rotas nem sómbolos `.sema` sem contrato.
-
-
-Este documento descreve o vertical oficial de pagamento da Sema no fluxo público atual.
-
-O objetivo não é mostrar um exemplo fofo. O objetivo e demonstrar que a linguagem já consegue modelar um fluxo de negócio real com:
-
-- contrato público
-- segurança e autorizacao
-- classificacao de dados
-- segredos e proibicoes explicitas
-- regras
-- efeitos operacionais
-- execução, idempotencia, retry e compensacao
-- transicoes de estado
-- orquestração
-- erros publicos
-- testes executaveis com saída, status ou erro observavel
-
-## Arquivos de referência
-
-- `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 operação 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 pública
-
-A operação entra por:
-
-- `route processar_pagamento_publico`
-
-Esse contrato pública:
-
-- `pagamento_id`
-- `valor`
-- `token`
-
-É expoe:
-
-- `pagamento`
-- `status`
-- erros publicos coerentes com a `task`
-
-### Task interna
-
-A `task processar_pagamento` faz o trabalho central:
-
-- exige `authz`
-- classifica `dados`
-- declara `segredos`, `audit` e `forbidden`
-- valida entrada
-- consulta o gateway
-- persiste o pagamento
-- emite evento
-- notifica comprovante
-- registra auditoria
-- declara `execucao` com idempotencia, timeout, retry, compensacao e criticidade
-- garante consistencia da saída
-
-### Estado e transicoes
-
-O `state ciclo_pagamento` ancora o contrato de transicao:
-
-- `PENDENTE -> AUTORIZADO`
-- `AUTORIZADO -> PROCESSADO`
-- `PENDENTE -> RECUSADO`
-
-A `task` explícita quais transicoes ela realmente usa.
-
-### Flow de orquestração
-
-O `flow orquestracao_pagamento` demonstra:
-
-- passagem de contexto
-- confirmação em caso de sucesso
-- notificação 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`
-
-Também 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 domínio compartilhado em um módulo e a operação em outro módulo.
-
-### 2. Aplicar o formato canônico
-
-```bash
-sema formatar exemplos
-```
-
-### 3. Validar semanticamente
-
-```bash
-sema validar exemplos/pagamento.sema
-```
-
-### 4. Gerar código
-
-```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 já consegue demonstrar que:
-
-- modela contrato público
-- modela superficie sensível sem deixar segurança invisível
-- modela efeitos operacionais
-- modela falhas reais
-- modulariza domínio com `use`
-- declara idempotencia e execução crítica sem criar sintaxe nova
-- gera artefatos coerentes para TypeScript e Python
-- executa testes gerados sem gambiarra conceitual
-
-Esse e o criterio pratico que sustenta o uso público do vertical de pagamento como referência para IA e geracao.

package/docs/persistencia-vendor-first.md

@@ -1,151 +0,0 @@
-# Persistência Vendor-First
-
-<!-- sema:i18n -->
-> EN: English first. The canonical operational body below may still be in Portuguese until full translation lands.
-> PT: Português depois, com acentos preservados.
-> ES: Español al final; não traduza comandos, rotas nem sómbolos `.sema` sem contrato.
-
-
-Sema 1.5.29 trata banco como superficie semântica de primeira classe. Isso significa assumir diferenças reais entre engines e coloca-las no contrato, no semântico, na IR, no drift, no impact map, na renomeacao assistida, no `verificar` e na extensao. Nesta linha, o `drift` também materializa persistência local real em `Preferences`, `localStorage` e `sessionStorage` quando a task está ancorada no arquivo que usa essas APIs, preservando o framing IA-first da release atual.
-
-## 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 explícito quando o contrato está pedindo portabilidade falsa, por exemplo:
-
-- `table` em `redis`
-- `foreign_keys` em engine sem suporte equivalente
-- transação multi-documento tratada como universal
-
-## Onde isso aparece
-
-- parser e AST
-- IR canonica
-- analisador semântico
-- formatador
-- `sema drift`
-- `sema importar`
-- extensao VS Code