@semacode/cli 1.5.48 → 1.5.53

package/docs/sintaxe.md

@@ -1,390 +0,0 @@
-<!-- sema:agent-entrypoint:start -->
-# Sintaxe Sema Para IA
-
-Use este arquivo como referencia curta antes de criar ou corrigir contratos `.sema`.
-
-## Regra de ouro
-
-Contrato vem antes de codigo. Antes de escrever `.sema`, consulte os exemplos locais em `exemplos/`.
-
-## Exemplo minimo
-
-```sema
-module app.exemplo {
-  entity Item {
-    fields {
-      id: Id
-      nome: Texto
-      ativo: Booleano
-    }
-  }
-
-  task criar_item {
-    input {
-      nome: Texto required
-    }
-    output {
-      item: Item
-    }
-    rules {
-      nome deve_ser preenchido
-    }
-    effects {
-      persistencia Item
-      auditoria item_criado
-    }
-    guarantees {
-      item existe
-    }
-    tests {
-      caso "cria item valido" {
-        given { nome: "Item" }
-        expect { sucesso: verdadeiro }
-      }
-    }
-  }
-}
-```
-
-## Blocos mais usados
-
-- `docs`: resumo e notas do modulo.
-- `entity`: modelo de dominio.
-- `task`: operacao governada.
-- `input` e `output`: contrato de entrada e saida.
-- `rules`: validacoes e regras de negocio.
-- `effects`: persistencia, consulta, evento, auditoria e chamadas externas.
-- `guarantees`: o que a task precisa entregar se tiver sucesso.
-- `error`: erros nomeados e mensagens.
-- `tests`: casos minimos de comportamento.
-- `route`: superficie publica vinculada a uma task.
-- `impl` e `vinculos`: ligacao entre contrato e codigo real.
-
-## Origens canonicas de `use` e `impl`
-
-Use estas origens em contratos antes de inventar palavra nova:
-
-- `ts` ou `typescript`
-- `js` ou `javascript`
-- `py` ou `python`
-- `dart`
-- `lua`
-- `cs` ou `dotnet`
-- `java`
-- `go`
-- `rust`
-- `cpp`
-
-Exemplos:
-
-```sema
-use javascript app.web.despesas
-
-impl {
-  js: src.app.salvarDespesa
-}
-```
-
-`sema compilar --alvo javascript` define o alvo de geracao. `impl { js: ... }` define a origem do codigo vivo ligado ao contrato. Sao camadas diferentes e ambas sao validas.
-
-## Listas canonicas pequenas
-
-- `effects`: `persistencia`, `consulta`, `evento`, `auditoria`, `db.write`, `queue.publish`, `fs.write`, `network.egress`, `secret.read`, `shell.exec`.
-- `audit.motivo`: `obrigatorio`, `opcional`, `dispensado`.
-
-## Tamanho de contrato .sema
-
-- ate 300 linhas: saudavel
-- 301-500 linhas: diagnostico, planeje split
-- acima de 500: bloqueia criacao, edicao, drift, finalizacao, geracao e snapshot
-- divida por dominio/capacidade real, como `despesas_cadastro.sema`, `despesas_totais.sema`, `despesas_persistencia.sema`
-- nunca use `parte_1`, `parte_2`, `part_3` ou nomes equivalentes
-- nao remova `guarantees`, `tests`, `authz`, `dados` ou `vinculos` so para caber no limite
-- varios contratos `.sema` podem governar o mesmo arquivo de codigo via `vinculos`; isso e esperado
-
-## JavaScript existe
-
-A CLI suporta geracao JavaScript. Use:
-
-```bash
-sema compilar contratos/pedidos.sema --alvo javascript --saida ./generated/javascript
-```
-
-O projeto tambem pode gerar TypeScript, Python, Dart, Lua, HTML e CSS quando esses alvos estiverem em `sema.config.json`.
-
-## Arquivos de apoio
-
-- `AGENTS.md`: regras obrigatorias do agente.
-- `SEMA_BOOT.md`: primeira leitura para qualquer IA.
-- `SEMA_SMALL_MODEL.md`: versao curta para IA fraca.
-- `AGENT_CONTEXT_PACK.json`: pacote estruturado para agentes.
-- `SEMA_INDEX.json`: indice do projeto.
-- `docs/comandos.md`: catalogo de comandos, gates e regra de `--saida`.
-- `exemplos/`: exemplos oficiais da DSL.
-
-Se a IA nao souber qual forma usar, ela deve abrir `exemplos/calculadora.sema`, `exemplos/crud_simples.sema`, `exemplos/pagamento.sema` ou `exemplos/tratamento_erro.sema` antes de inventar sintaxe.
-
-Politica de plataforma: O Sema governa contrato, escopo, drift, evidência e qualidade do projeto. Ele não pede, não autoriza e não contorna políticas da plataforma, termos de uso, permissões, segurança ou leis.
-<!-- sema:agent-entrypoint:end -->
-
-# 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`
-
-## Origens canonicas de `use` e `impl`
-
-Use estas origens em contratos antes de inventar palavra nova:
-
-- `ts` ou `typescript`
-- `js` ou `javascript`
-- `py` ou `python`
-- `dart`
-- `lua`
-- `cs` ou `dotnet`
-- `java`
-- `go`
-- `rust`
-- `cpp`
-
-Exemplos:
-
-```sema
-use javascript app.web.despesas
-
-task salvar_despesa {
-  input {
-    descricao: Texto required
-  }
-  output {
-    id: Id
-  }
-  impl {
-    js: src.app.salvarDespesa
-  }
-  guarantees {
-    id existe
-  }
-}
-```
-
-`sema compilar --alvo javascript` define alvo de geracao. `impl { js: ... }` define origem do codigo vivo. Nao troque uma coisa pela outra.
-
-## Listas canonicas pequenas
-
-- `effects`: `persistencia`, `consulta`, `evento`, `auditoria`, `db.write`, `queue.publish`, `fs.write`, `network.egress`, `secret.read`, `shell.exec`.
-- `audit.motivo`: `obrigatorio`, `opcional`, `dispensado`.
-
-## 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/llms-full.txt

@@ -1,40 +0,0 @@
-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`
-
-Platform policy:
-- Sema governs project contracts, scope, drift, evidence, language, semantic budget, and quality.
-- Sema does not bypass platform policy, terms, permissions, security, or law.
-- If a client/model blocks or warns, treat it as an external block or possible false positive; explain neutrally and do not try to bypass filters.
-
-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

@@ -1,23 +0,0 @@
-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
-
-Platform policy:
-- Sema governs project contracts, scope, drift, evidence, language, semantic budget, and quality.
-- Sema does not bypass platform policy, terms, permissions, security, or law.
-- If a client/model blocks or warns, treat it as an external block or possible false positive; explain neutrally and do not try to bypass filters.
-
-Prefer Sema artifacts over raw source code when both exist.
-Prefer `drift`, `briefing`, `ir`, and `diagnosticos` over guesswork.