@semacode/cli 1.2.17 → 1.3.0

package/docs/fluxo-pratico-ia-sema.md

@@ -1,177 +0,0 @@
-# Fluxo Pratico para IA Antes de Editar `.sema`
-
-Este documento descreve o fluxo operacional recomendado para qualquer IA antes, durante e depois de alterar arquivos `.sema`.
-
-Se a IA seguir isso, ela trabalha com contexto. Se nao seguir, vira adivinhacao gourmet.
-
-## Fluxo curto
-
-1. ler contexto do projeto
-2. identificar a capacidade da IA
-3. identificar o modulo alvo
-4. consultar o menor artefato semantico suficiente
-5. editar
-6. formatar
-7. validar
-8. verificar
-
-## Fluxo detalhado
-
-### Etapa 1. Ler contexto minimo
-
-Antes de tocar em qualquer arquivo, a IA deve ler:
-
-- [README.md](../README.md)
-- [integracao-com-ia.md](./integracao-com-ia.md)
-- [como-ensinar-a-sema-para-ia.md](./como-ensinar-a-sema-para-ia.md)
-
-Se o trabalho estiver ligado a pagamento, ler tambem:
-
-- [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
-
-### Etapa 2. Escolher a faixa de capacidade
-
-Antes de despejar contexto na IA, escolha o que ela aguenta:
-
-- IA pequena ou gratuita: `sema resumo --micro` e `briefing.min.json`
-- IA media: `sema resumo --curto`, `briefing.min.json` e `drift.json`
-- IA grande: `contexto-ia`, `briefing.json`, `drift.json`, `ir.json` e `ast.json`
-
-### Etapa 3. Ler o modulo alvo e um exemplo parecido
-
-A IA deve identificar:
-
-- qual arquivo sera editado
-- qual modulo esse arquivo representa
-- qual exemplo oficial mais se parece com o que precisa ser feito
-
-Regra pratica:
-
-- automacao: [automacao.sema](../exemplos/automacao.sema)
-- erros e fluxos de falha: [tratamento_erro.sema](../exemplos/tratamento_erro.sema)
-- borda publica e pagamento: [pagamento.sema](../exemplos/pagamento.sema)
-
-### Etapa 4. Consultar AST e IR quando fizer sentido
-
-Antes de alterar, a IA deve executar:
-
-```bash
-sema resumo caminho/arquivo.sema --curto --para mudanca
-sema ast caminho/arquivo.sema --json
-sema ir caminho/arquivo.sema --json
-```
-
-Objetivo:
-
-- ver a forma sintatica quando a capacidade aguentar
-- ver a forma semantica resolvida quando a capacidade aguentar
-- evitar interpretar errado o contrato
-
-### Etapa 5. Editar o `.sema`
-
-Ao editar, a IA deve:
-
-- preservar a intencao do modulo
-- seguir a gramatica existente
-- evitar criar bloco ou operador nao suportado
-- preferir a forma ja usada nos exemplos oficiais
-
-### Etapa 6. Formatar
-
-Depois da edicao:
-
-```bash
-sema formatar caminho/arquivo.sema
-sema formatar caminho/arquivo.sema --check
-```
-
-Se `--check` falhar, o trabalho ainda nao esta pronto.
-
-### Etapa 7. Validar e diagnosticar
-
-Depois da formatacao:
-
-```bash
-sema validar caminho/arquivo.sema --json
-sema diagnosticos caminho/arquivo.sema --json
-```
-
-Se houver falha:
-
-- usar os diagnosticos estruturados como contrato de correcao
-- nao insistir em leitura manual teimosa quando a CLI ja disse onde esta a merda
-
-### Etapa 7.5. Compilar quando a tarefa pedir codigo derivado
-
-Se a tarefa nao for so editar contrato, mas tambem gerar base de implementacao, a IA deve rodar explicitamente:
-
-```bash
-sema compilar caminho/arquivo.sema --alvo typescript --saida ./saida/typescript
-```
-
-Ou trocar o alvo para `python` ou `dart`, conforme o caso.
-
-Regra pratica:
-
-- se a entrega inclui codigo derivado, `sema compilar` nao e opcional
-- se a IA ignorar `compilar`, ela pode acabar reescrevendo na mao coisa que a Sema ja gera sozinha, que e burrice operacional
-
-### Etapa 8. Verificar
-
-No fechamento:
-
-```bash
-sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
-```
-
-## Fluxo minimo para automacao
-
-Se voce quiser o menor fluxo aceitavel para uma IA pequena:
-
-```bash
-sema resumo caminho/arquivo.sema --micro --para mudanca
-sema formatar caminho/arquivo.sema
-sema validar caminho/arquivo.sema --json
-```
-
-Mas, sendo sincero, o fluxo bom mesmo e fechar com `verificar`.
-
-Se a tarefa envolver codigo derivado, o fluxo minimo aceitavel vira:
-
-```bash
-sema ir caminho/arquivo.sema --json
-sema formatar caminho/arquivo.sema
-sema validar caminho/arquivo.sema --json
-sema compilar caminho/arquivo.sema --alvo typescript --saida ./saida/typescript
-```
-
-## Checklist de saida
-
-Antes de considerar a alteracao pronta, a IA deve responder mentalmente:
-
-- eu entendi o modulo e o contrato?
-- eu mantive a sintaxe dentro do que a linguagem suporta?
-- eu formatei o arquivo?
-- eu validei?
-- eu olhei diagnosticos se algo falhou?
-- eu fechei com verificacao?
-
-Se alguma resposta for "nao", ainda nao terminou.
-
-## Regra de ouro
-
-Em Sema, a IA nao deveria operar no escuro.
-
-Ela deve trabalhar sempre com:
-
-- exemplo oficial
-- AST
-- IR
-- diagnosticos
-- formatador
-
-Esse conjunto e o que faz a linguagem ser amigavel para IA de verdade, e nao so no discurso bonito.
-
-## Observacao sobre caminhos
-
-Esta documentacao usa placeholders de arquivo e pasta, nao caminhos do monorepo da Sema. A IA deve adaptar isso ao projeto atual e continuar tratando `sema` como interface publica principal.

package/docs/instalacao-e-primeiro-uso.md

@@ -1,196 +0,0 @@
-# Instalacao e Primeiro Uso
-
-Este guia mostra o caminho mais curto para testar a Sema do jeito certo, sem misturar fluxo de usuario com gambiarra de contribuinte.
-
-## Requisitos
-
-- Node.js instalado
-- npm funcionando
-- Python 3 e `pytest` se voce quiser rodar o fluxo completo de testes Python gerados
-
-O repositorio so e necessario se voce quiser contribuir na Sema, rodar o showcase oficial localmente ou empacotar release.
-
-## Caminho oficial
-
-Instalacao via npm:
-
-```bash
-npm install -g @semacode/cli
-sema --help
-sema doctor
-```
-
-Se preferir o tarball oficial da GitHub Release:
-
-```bash
-npm install -g https://github.com/gerlanss/Sema/releases/latest/download/sema-cli-latest.tgz
-sema --help
-sema doctor
-```
-
-Instalacao local ao projeto:
-
-```bash
-npm install @semacode/cli
-npx sema --help
-```
-
-Instaladores auxiliares para a linha publica atual:
-
-- Linux/macOS: `curl -fsSL https://raw.githubusercontent.com/gerlanss/Sema/v1.0.0/install-sema.sh | bash`
-- Windows PowerShell: `irm https://raw.githubusercontent.com/gerlanss/Sema/v1.0.0/install-sema.ps1 | iex`
-
-Se voce quiser reproducao estrita, prefira o npm registry ou o tarball da GitHub Release.
-
-## Primeiro teste sem clonar o repo
-
-```bash
-mkdir sema-demo
-cd sema-demo
-sema iniciar
-sema validar contratos/pedidos.sema --json
-```
-
-## Primeiro fluxo util
-
-```bash
-sema validar contratos/pedidos.sema --json
-sema ast contratos/pedidos.sema --json
-sema ir contratos/pedidos.sema --json
-sema formatar contratos/pedidos.sema
-sema verificar contratos --saida ./.tmp/verificacao
-```
-
-## Primeiro fluxo de IA real
-
-Sem clonar o repo, o fluxo que mais mostra a proposta da Sema hoje e:
-
-```bash
-sema inspecionar . --json
-sema resumo contratos/pedidos.sema --micro --para mudanca
-sema drift contratos/pedidos.sema --json
-sema contexto-ia contratos/pedidos.sema --saida ./.tmp/contexto-pedidos --json
-```
-
-Esse fluxo mostra:
-
-- base de projeto resolvida
-- cartao semantico curto para IA pequena ou gratuita
-- codigo vivo detectado
-- `impl` e `vinculos` resolvidos
-- score, confianca e lacunas do `drift`
-- `briefing.min.json` e `briefing.json` para IA antes da edicao
-
-## `sema.config.json`
-
-Exemplo de configuracao para projeto real:
-
-```json
-{
-  "origens": ["./contratos"],
-  "saida": "./generated",
-  "alvos": ["typescript", "python"],
-  "alvoPadrao": "typescript",
-  "estruturaSaida": "backend",
-  "framework": "nestjs",
-  "modoEstrito": true,
-  "diretoriosSaidaPorAlvo": {
-    "typescript": "./generated/nestjs",
-    "python": "./generated/fastapi"
-  },
-  "convencoesGeracaoPorProjeto": "backend"
-}
-```
-
-## Gerar codigo
-
-Scaffold base:
-
-```bash
-sema compilar contratos/pedidos.sema --alvo typescript --saida ./saida/typescript
-sema compilar contratos/pedidos.sema --alvo python --saida ./saida/python
-sema compilar contratos/pedidos.sema --alvo dart --saida ./saida/dart
-```
-
-Scaffold backend:
-
-```bash
-sema compilar contratos/pedidos.sema --alvo typescript --framework nestjs --estrutura backend --saida ./generated/nestjs
-sema compilar contratos/pedidos.sema --alvo python --framework fastapi --estrutura backend --saida ./generated/fastapi
-```
-
-## Extensao VS Code
-
-Via GitHub Release:
-
-```bash
-curl -L -o sema-language-tools.vsix https://github.com/gerlanss/Sema/releases/latest/download/sema-language-tools-latest.vsix
-code --install-extension ./sema-language-tools.vsix --force
-```
-
-Windows PowerShell:
-
-```powershell
-Invoke-WebRequest -Uri https://github.com/gerlanss/Sema/releases/latest/download/sema-language-tools-latest.vsix -OutFile sema-language-tools.vsix
-code --install-extension .\sema-language-tools.vsix --force
-```
-
-Pagina oficial:
-
-- [https://github.com/gerlanss/Sema/releases/latest](https://github.com/gerlanss/Sema/releases/latest)
-
-Se voce estiver desenvolvendo a propria extensao localmente, ai sim entra a trilha de contribuinte:
-
-```bash
-npm run extensao:empacotar
-npm run extensao:instalar-local
-```
-
-## Caminho de contribuinte
-
-Se o objetivo for desenvolver a propria Sema:
-
-```bash
-npm install
-npm run build
-npm run cli:instalar-local
-sema validar exemplos/calculadora.sema
-```
-
-Se quiser validar tudo de cara:
-
-```bash
-npm run project:check
-```
-
-## `npm link` continua existindo
-
-Esse fluxo continua util, mas e trilha de contribuinte:
-
-```powershell
-npm run cli:instalar-local
-```
-
-Serve para:
-
-- testar a experiencia de terminal no proprio ambiente
-- desenvolver a CLI
-- usar `sema` como interface principal mesmo durante o desenvolvimento local
-
-Para remover:
-
-```powershell
-npm run cli:desinstalar-local
-```
-
-## Resumo honesto
-
-Hoje o jeito certo de testar a Sema e:
-
-1. instalar a CLI pelo npm ou pela GitHub Release
-2. rodar `sema iniciar`
-3. validar `contratos/pedidos.sema`
-4. usar `inspecionar -> resumo -> drift -> contexto-ia` quando o projeto for vivo
-5. ler `briefing.min.json` ou `briefing.json` antes de mandar a IA sair cavando arquivo
-
-Clone + build + `npm link` continua bom para oficina, nao para landing page publica.

package/docs/integracao-com-ia.md

@@ -1,228 +0,0 @@
-# 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.
-
-## Moldura correta
-
-Se uma IA tratar a Sema como enfeite declarativo, ela vai usar mal. A moldura certa e esta:
-
-- `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
-
-Em resumo: a Sema nao serve para a IA adivinhar melhor. Ela serve para a IA precisar adivinhar menos.
-
-## Fluxo recomendado
-
-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`
-- `briefing.min.json`
-
-No minimo, para IA media:
-
-- `resumo.curto.txt`
-- `briefing.min.json`
-- `drift.json`
-
-No minimo, para IA grande:
-
-- `ir.json`
-- `drift.json`
-- `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:
-
-```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
-```
-
-Quando a tarefa nasce num legado:
-
-```bash
-sema importar flask ./backend-flask --saida ./sema/importado --json
-sema formatar ./sema/importado
-sema validar ./sema/importado --json
-sema drift ./sema/importado --json
-```
-
-## Showcase oficial do repo
-
-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
-```
-
-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.
-
-## Fechamento operacional
-
-Quando a IA terminar a mudanca fora do monorepo:
-
-```bash
-sema formatar contratos/modulo.sema
-sema validar contratos/modulo.sema --json
-sema verificar contratos --json --saida ./.tmp/verificacao-final
-```