@semacode/cli 1.5.31 → 1.5.32

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"
+}

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

@@ -1,14 +1,7 @@
-{
-  "name": "@sema/gerador-typescript",
-  "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-typescript",
+  "version": "1.5.29",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts"
+}

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

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

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

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