@semacode/cli 1.3.7 → 1.4.0

package/docs/integracao-com-ia.md

@@ -1,228 +1,71 @@
 # Integracao com IA
 
-A Sema foi desenhada para IA editar backend vivo com menos chute. O ponto nao e "a IA gera tudo"; o ponto e deixar contrato, vinculo e contexto operacional estruturados o bastante para a IA nao trabalhar igual um bicho tonto. Leitura humana continua possivel, mas nao e o centro do desenho.
+Sema foi feita para IA operar software vivo com menos adivinhacao.
 
-## Moldura correta
+## Ordem recomendada
 
-Se uma IA tratar a Sema como enfeite declarativo, ela vai usar mal. A moldura certa e esta:
+1. `sema inspecionar . --json`
+2. `sema resumo <arquivo-ou-pasta> --micro --para onboarding`
+3. `sema drift <arquivo-ou-pasta> --json`
+4. `sema contexto-ia <arquivo.sema> --saida <diretorio> --json`
 
-- `impl` liga intencao a simbolo executavel
-- `vinculos` ligam contrato a arquivo, simbolo, recurso e superficie real
-- `execucao` explicita timeout, retry, compensacao e criticidade
-- `drift` mede verdade contra codigo vivo
-- `contexto-ia` empacota briefing operacional antes da edicao
+Nao comece cavando codigo bruto quando a ferramenta ja consegue te dar contrato, score, lacuna e superficie viva.
 
-Em resumo: a Sema nao serve para a IA adivinhar melhor. Ela serve para a IA precisar adivinhar menos.
+## Por capacidade do modelo
 
-## Fluxo recomendado
+IA pequena:
 
-Quando o trabalho cair em projeto vivo, o fluxo canonico agora e:
-
-```bash
-sema inspecionar . --json
-sema resumo contratos/modulo.sema --micro --para mudanca
-sema drift contratos/modulo.sema --json
-sema contexto-ia contratos/modulo.sema --saida ./.tmp/contexto --json
-```
-
-Leitura rapida:
-
-1. `inspecionar` descobre base do projeto, diretorios de codigo, fontes legado e modulos relevantes.
-2. `resumo` entrega o menor cartao semantico util para a IA atual.
-3. `drift` mede impls, vinculos, rotas, recursos, score semantico e confianca.
-4. `contexto-ia` gera o pacote que a IA deveria ler antes de editar.
-
-## Capacidade da IA
-
-A Sema agora assume explicitamente que nem toda IA aguenta o pacote completo.
-
-- IA pequena ou gratuita: comece em `resumo.micro.txt`, `briefing.min.json` e `prompt-curto.txt`
-- IA media: suba para `resumo.curto.txt`, `briefing.min.json` e `drift.json`
-- IA grande ou com tool use: leia `README.md`, `resumo.md`, `briefing.json`, `drift.json`, `ir.json` e `ast.json`
-
-Se voce joga `ast.json` inteiro em modelo pequeno e depois reclama da resposta, foi voce que fez cagada operacional.
-
-## O que a IA deve consumir
-
-No minimo, para IA pequena:
-
-- `resumo.micro.txt`
+- `sema resumo --micro`
 - `briefing.min.json`
+- `prompt-curto.txt`
 
-No minimo, para IA media:
+IA media:
 
-- `resumo.curto.txt`
-- `briefing.min.json`
+- `sema resumo --curto`
 - `drift.json`
+- `briefing.min.json`
 
-No minimo, para IA grande:
+IA grande:
 
-- `ir.json`
-- `drift.json`
+- `sema contexto-ia`
 - `briefing.json`
-- o proprio contrato `.sema`
-
-O `briefing.json` agora e a peca mais operacional do pacote. Ele responde perguntas que agente serio precisa responder antes de mexer em codigo:
-
-- o que tocar
-- o que validar
-- o que esta frouxo
-- o que foi inferido
-- quais simbolos estao relacionados
-- quais superficies publicas podem ser afetadas
-- quais testes minimos rodar
-
-## Saida relevante do pacote `contexto-ia`
-
-Hoje o pacote pode incluir:
-
-- `resumo.micro.txt`
-- `resumo.curto.txt`
-- `resumo.md`
-- `briefing.min.json`
-- `prompt-curto.txt`
-- `ast.json`
 - `ir.json`
-- `diagnosticos.json`
-- `drift.json`
-- `briefing.json`
-- `README.md`
-- `impl.<origem>.txt` quando existir implementacao vinculada
-
-## Score, confianca e risco
-
-`drift`, `inspecionar` e `contexto-ia` passam a expor sinais que ajudam a IA a nao tratar rascunho como verdade absoluta:
-
-- `scoreSemantico`
-- `confiancaVinculo`
-- `riscoOperacional`
-- `lacunas`
-- `vinculos_validos`
-- `vinculos_quebrados`
-
-Leitura pratica:
-
-- score alto + confianca alta: a IA pode editar com trilha boa
-- score medio: ainda precisa ler contrato e conferir codigo vivo
-- vinculo quebrado: a IA deve reduzir ousadia e consertar rastreabilidade antes de refatorar igual doida
-
-## Superficies que a IA pode esperar
-
-A linguagem agora trata estas bordas como primeira classe:
-
-- `route`
-- `worker`
-- `evento`
-- `fila`
-- `cron`
-- `webhook`
-- `cache`
-- `storage`
-- `policy`
-
-Isso importa porque backend real nao vive so de HTTP. Se a IA vai editar stack viva, ela precisa enxergar job, evento, webhook e recurso assincrono como parte do contrato, nao como sobra esquecida no runtime.
-
-## Contrato operacional
-
-Dentro de `task` e superficies, a IA deve prestar atencao em:
-
-- `input`
-- `output`
-- `effects`
-- `impl`
-- `vinculos`
-- `execucao`
-- `guarantees`
-- `error`
-
-Exemplo minimo:
-
-```sema
-task medir_drift {
-  input {
-    contrato: Texto required
-  }
-  output {
-    score: Decimal
-  }
-  impl {
-    ts: cli.src.drift.analisarDriftLegado
-  }
-  vinculos {
-    arquivo: "pacotes/cli/src/drift.ts"
-    simbolo: cli.src.drift.analisarDriftLegado
-  }
-  execucao {
-    timeout: "30s"
-    retry: "3x exponencial"
-    criticidade_operacional: alta
-  }
-  guarantees {
-    score existe
-  }
-}
-```
-
-## Comandos que agente serio nao deveria ignorar
-
-- `sema ast arquivo.sema --json`
-- `sema ir arquivo.sema --json`
-- `sema validar arquivo.sema --json`
-- `sema diagnosticos arquivo.sema --json`
-- `sema formatar arquivo.sema`
-- `sema inspecionar [arquivo-ou-pasta] --json`
-- `sema drift [arquivo-ou-pasta] --json`
-- `sema contexto-ia arquivo.sema [--saida <diretorio>] --json`
-- `sema verificar [arquivo-ou-pasta] --json`
-
-## Fluxos comuns
-
-Quando a tarefa for so modelagem:
-
-```bash
-sema ast contratos/pedidos.sema --json
-sema ir contratos/pedidos.sema --json
-sema formatar contratos/pedidos.sema
-sema validar contratos/pedidos.sema --json
-```
-
-Quando a tarefa envolver codigo derivado:
+- `ast.json`
 
-```bash
-sema inspecionar . --json
-sema drift contratos/pedidos.sema --json
-sema contexto-ia contratos/pedidos.sema --saida ./.tmp/contexto-pedidos --json
-sema compilar contratos/pedidos.sema --alvo typescript --framework nestjs --estrutura backend --saida ./generated/nestjs
-```
+## MCP
 
-Quando a tarefa nasce num legado:
+Se o agente usa MCP:
 
 ```bash
-sema importar flask ./backend-flask --saida ./sema/importado --json
-sema formatar ./sema/importado
-sema validar ./sema/importado --json
-sema drift ./sema/importado --json
+npm install -g @semacode/cli @semacode/mcp
 ```
 
-## Showcase oficial do repo
+Depois configure:
 
-Se voce estiver no monorepo da Sema, o showcase [showcases/ranking-showroom](../showcases/ranking-showroom/) continua sendo a melhor vitrine do fluxo completo:
-
-```bash
-cd showcases/ranking-showroom
-sema inspecionar . --json
-sema drift contratos/ranking_showroom.sema --json
-sema contexto-ia contratos/ranking_showroom.sema --saida ./.tmp/contexto-ranking --json
+```json
+{
+  "mcpServers": {
+    "sema": {
+      "command": "npx",
+      "args": ["-y", "@semacode/mcp"]
+    }
+  }
+}
 ```
 
-O valor aqui nao e so "validou". O valor e sair com score, confianca, drift e briefing suficientes para editar o backend Flask real sem sair cavando arquivo a esmo.
+## Regras praticas
 
-## Fechamento operacional
+- trate `.sema` e IR como fonte de verdade semantica
+- trate `drift` como juiz da adocao incremental
+- use `briefing.min.json` antes de abrir dezenas de arquivos
+- nao invente sintaxe fora da gramatica oficial
+- em persistencia, nao assuma que bancos diferentes tem o mesmo contrato operacional
 
-Quando a IA terminar a mudanca fora do monorepo:
+## Arquivos uteis no repo
 
-```bash
-sema formatar contratos/modulo.sema
-sema validar contratos/modulo.sema --json
-sema verificar contratos --json --saida ./.tmp/verificacao-final
-```
+- `AGENTS.md`
+- `llms.txt`
+- `llms-full.txt`
+- `SEMA_BRIEF.md`
+- `SEMA_INDEX.json`
+- `docs/persistencia-vendor-first.md`

package/docs/persistencia-vendor-first.md

@@ -0,0 +1,145 @@
+# Persistencia Vendor-First
+
+Sema 1.4.0 trata banco como superficie semantica de primeira classe. Isso significa assumir diferencas reais entre engines e coloca-las no contrato, no semantico, no IR, no drift e na extensao.
+
+## 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 explicito quando o contrato esta pedindo portabilidade falsa, por exemplo:
+
+- `table` em `redis`
+- `foreign_keys` em engine sem suporte equivalente
+- transacao multi-documento tratada como universal
+
+## Onde isso aparece
+
+- parser e AST
+- IR canonica
+- analisador semantico
+- formatador
+- `sema drift`
+- `sema importar`
+- extensao VS Code