@semacode/cli 0.9.0 → 1.0.0

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

@@ -7,12 +7,13 @@ Se a IA seguir isso, ela trabalha com contexto. Se nao seguir, vira adivinhacao
 ## Fluxo curto
 
 1. ler contexto do projeto
-2. identificar o modulo alvo
-3. consultar AST e IR
-4. editar
-5. formatar
-6. validar
-7. verificar
+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
 
@@ -28,7 +29,15 @@ Se o trabalho estiver ligado a pagamento, ler tambem:
 
 - [pagamento-ponta-a-ponta.md](./pagamento-ponta-a-ponta.md)
 
-### Etapa 2. Ler o modulo alvo e um exemplo parecido
+### 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:
 
@@ -42,22 +51,23 @@ Regra pratica:
 - erros e fluxos de falha: [tratamento_erro.sema](../exemplos/tratamento_erro.sema)
 - borda publica e pagamento: [pagamento.sema](../exemplos/pagamento.sema)
 
-### Etapa 3. Consultar AST e IR
+### Etapa 4. Consultar AST e IR quando fizer sentido
 
 Antes de alterar, a IA deve executar:
 
 ```bash
-node pacotes/cli/dist/index.js ast caminho\\arquivo.sema --json
-node pacotes/cli/dist/index.js ir caminho\\arquivo.sema --json
+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
-- ver a forma semantica resolvida
+- ver a forma sintatica quando a capacidade aguentar
+- ver a forma semantica resolvida quando a capacidade aguentar
 - evitar interpretar errado o contrato
 
-### Etapa 4. Editar o `.sema`
+### Etapa 5. Editar o `.sema`
 
 Ao editar, a IA deve:
 
@@ -66,24 +76,24 @@ Ao editar, a IA deve:
 - evitar criar bloco ou operador nao suportado
 - preferir a forma ja usada nos exemplos oficiais
 
-### Etapa 5. Formatar
+### Etapa 6. Formatar
 
 Depois da edicao:
 
 ```bash
-node pacotes/cli/dist/index.js formatar caminho\\arquivo.sema
-node pacotes/cli/dist/index.js formatar caminho\\arquivo.sema --check
+sema formatar caminho/arquivo.sema
+sema formatar caminho/arquivo.sema --check
 ```
 
 Se `--check` falhar, o trabalho ainda nao esta pronto.
 
-### Etapa 6. Validar e diagnosticar
+### Etapa 7. Validar e diagnosticar
 
 Depois da formatacao:
 
 ```bash
-node pacotes/cli/dist/index.js validar caminho\\arquivo.sema --json
-node pacotes/cli/dist/index.js diagnosticos caminho\\arquivo.sema --json
+sema validar caminho/arquivo.sema --json
+sema diagnosticos caminho/arquivo.sema --json
 ```
 
 Se houver falha:
@@ -91,12 +101,12 @@ 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 6.5. Compilar quando a tarefa pedir codigo derivado
+### 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
-node pacotes/cli/dist/index.js compilar caminho\\arquivo.sema --alvo typescript --saida .\\saida\\typescript
+sema compilar caminho/arquivo.sema --alvo typescript --saida ./saida/typescript
 ```
 
 Ou trocar o alvo para `python` ou `dart`, conforme o caso.
@@ -106,28 +116,22 @@ 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 7. Verificar
+### Etapa 8. Verificar
 
 No fechamento:
 
 ```bash
-node pacotes/cli/dist/index.js verificar exemplos --json --saida ./.tmp/verificacao-ia
-```
-
-Ou, no fluxo consolidado do projeto:
-
-```bash
-npm run project:check
+sema verificar arquivo-ou-pasta --json --saida ./.tmp/verificacao-ia
 ```
 
 ## Fluxo minimo para automacao
 
-Se voce quiser o menor fluxo aceitavel para uma IA:
+Se voce quiser o menor fluxo aceitavel para uma IA pequena:
 
 ```bash
-node pacotes/cli/dist/index.js ir caminho\\arquivo.sema --json
-node pacotes/cli/dist/index.js formatar caminho\\arquivo.sema
-node pacotes/cli/dist/index.js validar caminho\\arquivo.sema --json
+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`.
@@ -135,10 +139,10 @@ Mas, sendo sincero, o fluxo bom mesmo e fechar com `verificar`.
 Se a tarefa envolver codigo derivado, o fluxo minimo aceitavel vira:
 
 ```bash
-node pacotes/cli/dist/index.js ir caminho\\arquivo.sema --json
-node pacotes/cli/dist/index.js formatar caminho\\arquivo.sema
-node pacotes/cli/dist/index.js validar caminho\\arquivo.sema --json
-node pacotes/cli/dist/index.js compilar caminho\\arquivo.sema --alvo typescript --saida .\\saida\\typescript
+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
@@ -170,4 +174,4 @@ Esse conjunto e o que faz a linguagem ser amigavel para IA de verdade, e nao so
 
 ## Observacao sobre caminhos
 
-Esta documentacao usa caminhos relativos ao repositorio, nao caminhos locais de maquina. Isso permite que qualquer pessoa clone o projeto e use os links e referencias sem depender de uma pasta especifica no proprio ambiente.
+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

@@ -0,0 +1,189 @@
+# 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
+
+Empacotar:
+
+```bash
+npm run extensao:empacotar
+```
+
+Instalar localmente:
+
+```bash
+npm run extensao:instalar-local
+```
+
+Ou manualmente:
+
+```bash
+code --install-extension .tmp/editor-vscode/sema-language-tools-1.0.0.vsix --force
+```
+
+## 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

@@ -0,0 +1,228 @@
+# 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
+```