@semacode/cli 1.5.31 → 1.5.34

package/docs/seguranca.md

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

package/docs/sintaxe.md

@@ -0,0 +1,218 @@
+# Sintaxe Canonica
+
+<!-- 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.
+
+
+A Sema usa blocos declarativos previsiveis para reduzir ambiguidade no parser, na IR, no drift e no contexto de IA. A escrita humana pode ser legivel, mas o alvo principal da sintaxe e gerar contrato consumivel por agente.
+
+## Regras basicas
+
+- um arquivo `.sema` contem um `module` principal
+- cada bloco abre com palavra-chave e fecha com `}`
+- campos usam `nome: valor`
+- blocos declarativos podem aparecer aninhados quando o contrato exigir
+- `tests` usa blocos `caso`
+
+## Blocos de primeira classe
+
+- `module`
+- `use`
+- `database`
+- `type`
+- `entity`
+- `enum`
+- `state`
+- `task`
+- `flow`
+- `route`
+- `worker`
+- `evento`
+- `fila`
+- `cron`
+- `webhook`
+- `cache`
+- `storage`
+- `policy`
+- `tests`
+- `docs`
+- `comments`
+
+## Subblocos comuns
+
+- `input`
+- `output`
+- `rules`
+- `effects`
+- `auth`
+- `authz`
+- `dados`
+- `audit`
+- `segredos`
+- `forbidden`
+- `impl`
+- `vinculos`
+- `execucao`
+- `guarantees`
+- `error`
+- `fields`
+- `invariants`
+- `transitions`
+- `given`
+- `when`
+- `expect`
+
+## Tipos primitivos
+
+Tipos primitivos reconhecidos diretamente:
+
+- `Texto`
+- `Numero`
+- `Inteiro`
+- `Decimal`
+- `Booleano`
+- `Data`
+- `Timestamp`
+- `Objeto`
+- `Id`
+- `Email`
+- `Json`
+
+`Timestamp` e `Objeto` funcionam como aliases primitivos suportados e preservam o texto original na IR.
+
+## Tipos compostos
+
+```sema
+input {
+  ids: Lista<Id> required
+  metadata: Mapa<Texto, Texto>
+  responsavel: Opcional<Usuario>
+  chave_publica: Texto|Id
+}
+```
+
+Formas suportadas:
+
+- `Lista<T>`
+- `Mapa<K, V>`
+- `Opcional<T>`
+- `T1|T2`
+- `T?`
+
+## Predicados normalizados
+
+Predicados escritos em contrato preservam o texto original em `predicado`. Quando a CLI reconhece uma forma comum, a expressao estruturada pode expor também `predicadoCanonico`.
+
+Exemplo:
+
+```sema
+rules {
+  email deve_ser email_valido
+  nome deve_ser preenchido
+}
+```
+
+Na IR, `email_valido` continua existindo como escrito e pode receber uma normalizacao como `valid_email`; `preenchido` pode receber `filled`. Esse campo e opcional e serve a agente/automacao, não muda a sintaxe pública.
+
+## Persistência vendor-first
+
+O bloco `database` modela banco e recursos persistidos sem apagar as diferenças entre engines.
+
+Estrutura base:
+
+```sema
+database principal_postgres {
+  engine: postgres
+  consistency: forte
+  durability: alta
+  transaction_model: mvcc
+  query_model: sql
+}
+```
+
+Recursos canonicamente suportados:
+
+- `table`
+- `index`
+- `relationship`
+- `query`
+- `retention`
+- `lock`
+- `replication`
+- `collection`
+- `document`
+- `keyspace`
+- `stream`
+- `capabilities`
+
+Exemplo relacional:
+
+```sema
+database principal_postgres {
+  engine: postgres
+  schema: public
+  capabilities {
+    joins
+    views
+    foreign_keys
+  }
+  table pedidos {
+    entity: Pedido
+  }
+  relationship pedido_cliente {
+    from: Pedido
+    to: Cliente
+  }
+  query buscar_pedidos {
+    mode: sql
+  }
+}
+```
+
+Exemplo documental:
+
+```sema
+database principal_mongodb {
+  engine: mongodb
+  query_model: documento
+  collection pedidos {
+    collection: pedidos
+  }
+  document pedido_snapshot {
+    entity: PedidoSnapshot
+  }
+  query pipeline_pedido {
+    mode: pipeline
+  }
+}
+```
+
+Exemplo key-value:
+
+```sema
+database principal_redis {
+  engine: redis
+  query_model: chave_valor
+  keyspace cache_pedidos {
+    ttl: "300s"
+  }
+  stream eventos_pedido {
+    surface: fila
+  }
+}
+```
+
+## Compatibilidade declarada
+
+O IR de persistência calcula compatibilidade por recurso com quatro estados:
+
+- `nativo`
+- `adaptado`
+- `parcial`
+- `invalido`
+
+Isso existe para deixar explícito quando um contrato está pedindo de um banco algo que ele não entrega do mesmo jeito.
+
+O mesmo principio vale para runtime de orquestração. Superfícies como `webhook`, `cron`, `worker`, `evento` e `fila` podem ser medidas contra famílias como `n8n`, mas o contrato continua canonicamente modelado em Sema, sem rebaixar a linguagem para a sintaxe do adapter alvo.

package/exemplos/profile_conversas.sema

@@ -0,0 +1,165 @@
+module exemplos.profile_conversas {
+  docs {
+    resumo: "Exemplo oficial do profile Conversas: bot comercial para atendimento de cliente com tom persuasivo, estado visivel do turno, customer_reply como unica saida ao cliente, deduplicacao, limites de promessa, memoria curta e escalacao humana. Contrato primeiro: criar, editar ou remover contrato antes de qualquer acao."
+  }
+
+  type PoliticaTomConversa {
+    fields {
+      tom: Texto
+      formalidade: Texto
+      intensidade_persuasiva: Texto
+      proibicoes: Lista
+    }
+    invariants {
+      tom existe
+      formalidade existe
+      intensidade_persuasiva existe
+      proibicoes existe
+    }
+  }
+
+  type ContextoClienteConversa {
+    fields {
+      etapa: Texto
+      intencao_detectada: Texto
+      sentimento: Texto
+      objecoes: Lista
+      historico_resumido: Texto
+      ultima_mensagem_cliente: Texto
+      ultima_resposta_visivel: Texto
+      fatos_coletados: Lista
+      proxima_acao_esperada: Texto
+    }
+    invariants {
+      etapa existe
+      intencao_detectada existe
+      sentimento existe
+      historico_resumido existe
+      ultima_mensagem_cliente existe
+      ultima_resposta_visivel existe
+      fatos_coletados existe
+      proxima_acao_esperada existe
+    }
+  }
+
+  type EstadoTurnoConversa {
+    fields {
+      conversation_id: Id
+      evento_id: Id
+      canal: Texto
+      mensagem_cliente_visivel: Texto
+      resposta_anterior_visivel: Texto
+      etapa_atual: Texto
+      pergunta_anterior: Texto
+      confirmacao_curta: Booleano
+      dedupe_key: Texto
+      origem_estado: Texto
+    }
+    invariants {
+      conversation_id existe
+      evento_id existe
+      canal existe
+      mensagem_cliente_visivel existe
+      resposta_anterior_visivel existe
+      etapa_atual existe
+      dedupe_key existe
+      origem_estado existe
+    }
+  }
+
+  task responder_cliente_vendas {
+    input {
+      mensagem_cliente: Texto required
+      contexto: ContextoClienteConversa required
+      politica: PoliticaTomConversa required
+      estado_turno: EstadoTurnoConversa required
+      conhecimento_autorizado: Lista required
+    }
+    output {
+      resposta_cliente: Texto
+      customer_reply: Texto
+      proxima_acao: Texto
+      escalar_humano: Booleano
+      dedupe_key: Texto
+    }
+    rules {
+      mensagem_cliente deve_ser preenchida
+      contexto deve_ser valido
+      politica deve_ser com_tom_comercial_persuasivo
+      estado_turno deve_ser origem_conversa_visivel
+      estado_turno deve_ser deduplicado_por_evento
+      conhecimento_autorizado deve_ser nao_vazio
+      estado_turno.confirmacao_curta deve_ser interpretada_contra_pergunta_anterior
+    }
+    effects {
+      auditoria conversa_cliente criticidade = alta
+      evento resposta_bot_preparada criticidade = media
+    }
+    authz {
+      escopo: sema.conversas.responder
+      tenant: obrigatorio
+    }
+    dados {
+      classificacao_padrao: interno
+      redacao_log: parcial
+    }
+    audit {
+      evento: exemplos.conversas.resposta
+      ator: auth.agente
+      correlacao: conversation_id
+      retencao: "30d"
+      motivo: obrigatorio
+    }
+    forbidden {
+      promessa_sem_base
+      inventar_preco_ou_prazo
+      insistencia_agressiva
+      ignorar_objecao_cliente
+      reiniciar_conversa_apos_confirmacao_curta
+      repetir_saudacao_apos_contexto_existente
+      enviar_json_interno_ao_cliente
+      responder_mais_de_uma_vez_o_mesmo_inbound
+      voz_generica_de_ia
+    }
+    impl {
+      ts: cli.src.index.validarProfileSemantico
+    }
+    vinculos {
+      arquivo: "pacotes/cli/src/index.ts"
+      simbolo: cli.src.index.validarProfileSemantico
+    }
+    execucao {
+      idempotencia: verdadeiro
+      timeout: "10s"
+      retry: "nenhum"
+      criticidade_operacional: alta
+    }
+    guarantees {
+      resposta_cliente existe
+      resposta_cliente deve_ser aderente_ao_tom
+      resposta_cliente deve_ser responder_objecao
+      customer_reply existe
+      customer_reply deve_ser unica_saida_visivel
+      proxima_acao existe
+      proxima_acao deve_ser clara
+      escalar_humano existe
+      dedupe_key existe
+    }
+    tests {
+      caso "lead indeciso recebe resposta com proxima acao" {
+        given {
+          mensagem_cliente: "Ainda estou comparando opcoes."
+          contexto: "etapa comparacao, intencao comprar, sentimento INDECISO, objecao confianca, ultima mensagem Ainda estou comparando opcoes, ultima resposta visivel vazia"
+          politica: "tom comercial persuasivo, formalidade media, proibido prometer preco ou prazo sem base"
+          estado_turno: "conversation_id c1 evento_id msg1 canal WHATSAPP mensagem_cliente_visivel Ainda estou comparando opcoes resposta_anterior_visivel vazia etapa_atual comparacao dedupe_key msg1 origem_estado conversa_visivel"
+          conhecimento_autorizado: "pode oferecer diagnostico rapido"
+        }
+
+        expect {
+          sucesso: verdadeiro
+          escalar_humano: falso
+        }
+      }
+    }
+  }
+}

package/llms-full.txt

@@ -0,0 +1,35 @@
+Sema is an AI-first semantic language and tooling stack for explicit software intent, drift analysis, and safer intervention in live backend systems.
+
+This repository is not optimized for human-first reading. It is optimized for AI agents that need compressed, canonical semantic context.
+
+Canonical entrypoints in the repository root:
+1. `llms.txt`
+2. `AGENT_CONTEXT_PACK.json`
+3. `SEMA_BRIEF.md`
+4. `SEMA_INDEX.json`
+5. `AGENTS.md`
+6. `README.md`
+7. `docs/AGENT_STARTER.md`
+
+Capacity routing:
+- small/free AI: `llms.txt` -> `AGENT_CONTEXT_PACK.json` -> `SEMA_BRIEF.micro.txt` -> `SEMA_INDEX.json` -> `AGENTS.md`
+- medium AI: `llms.txt` -> `AGENT_CONTEXT_PACK.json` -> `SEMA_BRIEF.curto.txt` -> `SEMA_INDEX.json` -> `AGENTS.md` -> `README.md`
+- large/tool-using AI: `llms-full.txt` -> `AGENT_CONTEXT_PACK.json` -> `SEMA_BRIEF.md` -> `SEMA_INDEX.json` -> `AGENTS.md` -> `README.md`
+
+Source-of-truth order:
+1. root Sema artifacts
+2. CLI JSON outputs
+3. official docs
+4. official examples
+5. raw implementation code
+
+Useful commands:
+- `sema resumo <arquivo-ou-pasta> --micro --para mudanca`
+- `sema prompt-curto <arquivo-ou-pasta> --curto --para review`
+- `sema drift <arquivo-ou-pasta> --json`
+- `sema contexto-ia <arquivo.sema> --saida ./.tmp/contexto --json`
+- `sema validar <arquivo-ou-pasta> --json`
+- `sema verificar <arquivo-ou-pasta> --json`
+
+Do not ask the model to infer semantics that are already available in Sema artifacts.
+Do not start from raw source code if `AGENT_CONTEXT_PACK`, `SEMA_BRIEF`, `SEMA_INDEX`, `drift`, or `briefing` are available.

package/llms.txt

@@ -0,0 +1,18 @@
+Sema is an AI-first semantic language and tooling stack for backend intent.
+
+This repository is not human-first. Use the canonical AI entrypoints before raw code.
+
+Read in this order:
+1. AGENT_CONTEXT_PACK.json
+2. SEMA_BRIEF.micro.txt or SEMA_BRIEF.md
+3. SEMA_INDEX.json
+4. AGENTS.md
+5. README.md
+
+Capacity routing:
+- small models: llms.txt -> AGENT_CONTEXT_PACK.json -> SEMA_BRIEF.micro.txt -> SEMA_INDEX.json -> AGENTS.md
+- medium models: llms.txt -> AGENT_CONTEXT_PACK.json -> SEMA_BRIEF.curto.txt -> SEMA_INDEX.json -> AGENTS.md -> README.md
+- large models: llms-full.txt -> AGENT_CONTEXT_PACK.json -> SEMA_BRIEF.md -> SEMA_INDEX.json -> AGENTS.md -> README.md
+
+Prefer Sema artifacts over raw source code when both exist.
+Prefer `drift`, `briefing`, `ir`, and `diagnosticos` over guesswork.

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

@@ -1,14 +1,7 @@
-{
-  "name": "@sema/gerador-css",
-  "version": "1.5.29",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc -p tsconfig.json"
-  },
-  "dependencies": {
-    "@sema/nucleo": "file:../nucleo",
-    "@sema/padroes": "file:../padroes"
-  }
-}
+{
+  "name": "@sema/gerador-css",
+  "version": "1.5.29",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts"
+}

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

@@ -1,14 +1,7 @@
-{
-  "name": "@sema/gerador-dart",
-  "version": "1.5.29",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc -p tsconfig.json"
-  },
-  "dependencies": {
-    "@sema/nucleo": "file:../nucleo",
-    "@sema/padroes": "file:../padroes"
-  }
-}
+{
+  "name": "@sema/gerador-dart",
+  "version": "1.5.29",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts"
+}

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

@@ -1,14 +1,7 @@
-{
-  "name": "@sema/gerador-html",
-  "version": "1.5.29",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc -p tsconfig.json"
-  },
-  "dependencies": {
-    "@sema/nucleo": "file:../nucleo",
-    "@sema/padroes": "file:../padroes"
-  }
-}
+{
+  "name": "@sema/gerador-html",
+  "version": "1.5.29",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts"
+}

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

@@ -1,14 +1,7 @@
-{
-  "name": "@sema/gerador-javascript",
-  "version": "1.5.29",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc -p tsconfig.json"
-  },
-  "dependencies": {
-    "@sema/nucleo": "file:../nucleo",
-    "@sema/padroes": "file:../padroes"
-  }
-}
+{
+  "name": "@sema/gerador-javascript",
+  "version": "1.5.29",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts"
+}

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

@@ -1,14 +1,7 @@
-{
-  "name": "@sema/gerador-lua",
-  "version": "1.5.29",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc -p tsconfig.json"
-  },
-  "dependencies": {
-    "@sema/nucleo": "file:../nucleo",
-    "@sema/padroes": "file:../padroes"
-  }
-}
+{
+  "name": "@sema/gerador-lua",
+  "version": "1.5.29",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts"
+}

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

@@ -1,14 +1,7 @@
-{
-  "name": "@sema/gerador-python",
-  "version": "1.5.29",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc -p tsconfig.json"
-  },
-  "dependencies": {
-    "@sema/nucleo": "file:../nucleo",
-    "@sema/padroes": "file:../padroes"
-  }
-}
+{
+  "name": "@sema/gerador-python",
+  "version": "1.5.29",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts"
+}