@semacode/cli 1.5.48 → 1.5.52

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

package/docs/prompt-base-ia-sema.md

@@ -1,111 +0,0 @@
-# Prompt-Base Oficial para IA Trabalhar com 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 arquivo serve como prompt-base oficial para qualquer IA que precise ler, escrever, revisar ou transformar arquivos `.sema`.
-
-O objetivo não é fazer a IA "improvisar bonito". O objetivo e fazer a IA operar a linguagem com previsibilidade. A Sema não foi desenhada para ergonomia humana como prioridade; ela foi desenhada para IA. Humanos escrevem, revisam e aprovam; o consumidor primário e o agente.
-
-## Prompt-base
-
-Use o texto abaixo como base:
-
-```text
-Voce esta trabalhando com Sema, um contrato semantico IA-first para agentes operarem software vivo.
-
-Tecnicamente, a Sema funciona como linguagem de intencao orientada a contrato. Operacionalmente, ela existe para governar semantica acima da stack e traduzir intencao operacional para IA, nao para substituir arquitetura, design ou aprovacao humana.
-
-Trate a Sema como contrato semantico executavel e protocolo de governanca IA-first. 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
-- use `predicadoCanonico` como normalizacao opcional; preserve o `predicado` original
-- 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 contrato semantico IA-first orientado a agente. 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 revisão
-
-Use está versão 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 está versão quando a IA for escrever módulo 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 diagnóstico
-
-Use está versão quando a IA já 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 até acertar. Com isso, ela trabalha direito.

package/docs/seguranca.md

@@ -1,126 +0,0 @@
-# Security
-
-<!-- sema:i18n -->
-> EN: English first.
-> PT: Português depois, com acentos preservados.
-> ES: Español al final.
-
-## EN
-
-The remote Sema MCP is a sensitive surface. It lets authorized agents read contracts, check drift, generate IA-first context, and operate inside allowed roots. Security depends on these controls working together:
-
-1. HTTPS on the public proxy.
-2. Commercial `sema_mcp_*` bearer key per request or OAuth authentication.
-3. `SEMA_MCP_PROJECT_ROOTS` pointing to a dedicated server root, for example `/srv/sema/projetos`.
-4. Contract-first operation before code, deploy, docs, workflow, Author text, game, legal, research, or ops actions.
-
-Do not publish the server without those controls.
-
-### Data That Must Not Leak
-
-- GitHub, npm, Supabase, SSH, or Git Credential Manager tokens.
-- Client-side `SEMA_MCP_AUTH_TOKEN` values containing `sema_mcp_*` keys.
-- `SEMA_MCP_OAUTH_SECRET`.
-- `SEMA_MCP_OAUTH_PASSCODE`.
-- Private key content.
-- `.env`, build caches, uploads, installed dependencies, or temporary snapshots with secrets.
-
-Operational runbooks may document non-secret references, such as the public domain, service name, and generic deployment role. They must never include private key bodies, private-key filenames, local key paths, non-public IPs, real server paths, or secret inventory details.
-
-### Remote Operation
-
-- Use the smallest privilege that still performs the job.
-- Do not log `Authorization` headers.
-- Do not publish `/mcp` with empty `SEMA_MCP_PROJECT_ROOTS`.
-- Keep Caddy or the reverse proxy with valid TLS.
-- Test `/mcp` without token and expect an authorization challenge.
-- Test account-scoped MCP tokens before declaring the product flow ready.
-
-### Incident
-
-If a secret appears in chat, screenshot, log, release, or Git history:
-
-1. Treat it as compromised.
-2. Rotate it at the provider.
-3. Remove it from the current file.
-4. If it reached Git, rewrite history or revoke it permanently.
-
-## PT
-
-O Sema MCP remoto é uma superfície sensível. Ele permite que agentes autorizados leiam contratos, verifiquem drift, gerem contexto IA-first e operem dentro das raízes permitidas. A segurança depende destas travas trabalhando juntas:
-
-1. HTTPS no proxy público.
-2. Autenticacao por chave comercial `sema_mcp_*` por request ou OAuth.
-3. `SEMA_MCP_PROJECT_ROOTS` apontando para uma raiz dedicada no servidor, por exemplo `/srv/sema/projetos`.
-4. Operação contract-first antes de código, deploy, docs, workflow, texto Author, jogo, jurídico, pesquisa ou ops.
-
-Não publique o servidor sem essas travas.
-
-### Dados Que Não Podem Vazar
-
-- Tokens de GitHub, npm, Supabase, SSH ou Git Credential Manager.
-- Valores locais de `SEMA_MCP_AUTH_TOKEN` contendo chaves `sema_mcp_*`.
-- `SEMA_MCP_OAUTH_SECRET`.
-- `SEMA_MCP_OAUTH_PASSCODE`.
-- Conteúdo de chave privada.
-- `.env`, caches de build, uploads, dependências instaladas ou snapshots temporários com segredo.
-
-Runbooks operacionais podem documentar referências não secretas, como domínio público, nome do serviço e papel genérico de deploy. Eles nunca devem incluir corpo de chave privada, nomes de arquivos de chave privada, caminhos locais de chave, IPs não públicos, caminhos reais de servidor ou detalhes do inventário de segredos.
-
-### Operação Remota
-
-- Use o menor privilégio que ainda executa o trabalho.
-- Não registre headers `Authorization` em logs.
-- Não publique `/mcp` com `SEMA_MCP_PROJECT_ROOTS` vazio.
-- Mantenha Caddy ou reverse proxy com TLS válido.
-- Teste `/mcp` sem token esperando desafio de autorização.
-- Teste tokens MCP por conta antes de declarar o fluxo de produto pronto.
-
-### Incidente
-
-Se um segredo aparecer em chat, print, log, release ou histórico Git:
-
-1. Considere comprometido.
-2. Rotacione no provedor de origem.
-3. Remova do arquivo atual.
-4. Se chegou ao Git, reescreva histórico ou revogue definitivamente o segredo.
-
-## ES
-
-El Sema MCP remoto es una superficie sensible. Permite que agentes autorizados lean contratos, verifiquen drift, generen contexto IA-first y operen dentro de las raíces permitidas. La seguridad depende de estos controles trabajando juntos:
-
-1. HTTPS en el proxy público.
-2. Autenticacion por clave comercial `sema_mcp_*` por request u OAuth.
-3. `SEMA_MCP_PROJECT_ROOTS` apuntando a una raíz dedicada en el servidor, por ejemplo `/srv/sema/projetos`.
-4. Operación contract-first antes de código, despliegue, docs, workflow, texto Author, juego, legal, investigación u ops.
-
-No publiques el servidor sin esos controles.
-
-### Datos Que No Deben Filtrarse
-
-- Tokens de GitHub, npm, Supabase, SSH o Git Credential Manager.
-- Valores locales de `SEMA_MCP_AUTH_TOKEN` con claves `sema_mcp_*`.
-- `SEMA_MCP_OAUTH_SECRET`.
-- `SEMA_MCP_OAUTH_PASSCODE`.
-- Contenido de llave privada.
-- `.env`, cachés de build, uploads, dependencias instaladas o snapshots temporales con secretos.
-
-Los runbooks operativos pueden documentar referencias no secretas, como dominio público, nombre del servicio y rol genérico de despliegue. Nunca deben incluir el cuerpo de la llave privada, nombres de archivos de llave privada, rutas locales de llaves, IPs no públicas, rutas reales del servidor o detalles del inventario de secretos.
-
-### Operación Remota
-
-- Usa el menor privilegio que todavía permita ejecutar el trabajo.
-- No registres headers `Authorization` en logs.
-- No publiques `/mcp` con `SEMA_MCP_PROJECT_ROOTS` vacío.
-- Mantén Caddy o el reverse proxy con TLS válido.
-- Prueba `/mcp` sin token y espera un desafío de autorización.
-- Prueba tokens MCP por cuenta antes de declarar listo el flujo de producto.
-
-### Incidente
-
-Si un secreto aparece en chat, captura, log, release o historial Git:
-
-1. Trátalo como comprometido.
-2. Rótalo en el proveedor de origen.
-3. Elimínalo del archivo actual.
-4. Si llegó a Git, reescribe el historial o revócalo definitivamente.