@semacode/cli 1.5.31 → 1.5.32

package/AGENTS.md

@@ -0,0 +1,294 @@
+# Sema — Regras obrigatorias para IA
+
+O Sema e o contrato semantico IA-first deste projeto.
+Toda IA deve consultar o Sema antes de qualquer acao sobre codigo ou contratos. Humanos escrevem e aprovam; agentes consomem o contrato para operar software vivo.
+
+## Regras
+
+1. Ao abrir o projeto, chame sema_resumo para entender o estado atual.
+2. Antes de criar qualquer modulo, rota, task ou contrato, chame sema_inspecionar no arquivo .sema mais proximo.
+3. Antes de editar codigo existente, chame sema_drift para verificar divergencias entre contrato e implementacao.
+4. Ao criar ou editar um arquivo .sema, chame sema_validar ao final.
+5. Nunca invente contratos — use o Sema para descobrir o que ja existe.
+6. Se qualquer ferramenta Sema retornar erro, corrija o problema antes de prosseguir — nao avance com codigo enquanto houver erros Sema pendentes.
+7. Contrato vem antes de qualquer acao: crie, edite ou remova o `.sema` aplicavel antes de codigo, deploy, docs operacionais, workflow, texto Author, game, legal, research ou ops.
+
+## MCP
+
+O servidor MCP do Sema e uma superficie privada/comercial acessada por endpoint remoto autorizado; ele nao e instalado por pacote npm publico neste repositorio.
+Use as ferramentas quando o endpoint privado estiver configurado: sema_resumo, sema_validar, sema_drift, sema_impacto, sema_renomear_semantico, sema_inspecionar, sema_ir, sema_verificar, sema_contexto_ia, sema_prompt_ia, sema_author_iniciar, sema_author_validar, sema_author_briefing, sema_author_revisar_cliches, sema_sync_ai_entrypoints, sema_instalar_exemplos, sema_docs_impacto, sema_finalizar_mudanca.
+
+O MCP deve deixar claro em toda orientacao: se nao existe contrato, crie; se a intencao mudou, edite; se a capacidade saiu, remova ou aposente. Isso vale para todo tipo de Sema: Software, Author, Workflow, Ops, Game, Legal, Research e profiles futuros.
+
+## Plataformas e Interfaces
+
+### IDEs com MCP (Roo Code, VS Code, Cursor, Windsurf, etc.)
+Quando usar MCP Sema configurado:
+1. Ao abrir o projeto, chame `sema_resumo` para entender o estado atual
+2. **ANTES DE QUALQUER AÇÃO**: chame `sema_docs_impacto` com sua intenção declarada
+3. Aguarde a resposta com as docs obrigatórias e leia-as antes de agir
+4. Use `sema_finalizar_mudanca` para comprovar que leu as docs
+
+### Web / Chat (ChatGPT, Lovable, etc.)
+Quando usar Sema via web sem MCP:
+1. Ao abrir o projeto, chame `sema_resumo` (se disponivel via web hook)
+2. **ANTES DE QUALQUER AÇÃO**: Declare sua intenção ao usuário
+3. Use `sema_docs_impacto` para descobrir docs obrigatórias (se via API)
+4. Leia as docs antes de agir e finalize com `sema_finalizar_mudanca`
+
+### CLI / Terminal
+Quando usar Sema via CLI:
+1. Execute `sema resumo` para entender o estado atual
+2. Execute `sema docs-impacto` antes de qualquer ação
+3. Leia as docs recomendadas antes de editar/criar/deletar
+4. Execute `sema finalizar-mudanca` ao concluir
+
+## Contratos e exemplos
+
+- Sempre salve arquivos .sema na pasta `contratos/` do projeto.
+- Crie um arquivo .sema por modulo ou contexto de negocio. Exemplo: `contratos/pedido.sema`, `contratos/pagamento.sema`, `contratos/usuario.sema`. Nunca coloque modulos de contextos diferentes no mesmo arquivo.
+- Antes de criar qualquer arquivo .sema, leia todos os arquivos da pasta `exemplos/` para entender o formato correto da linguagem.
+- Nunca edite os arquivos da pasta `exemplos/`.
+
+## Quando o projeto nao tem .sema
+
+Pergunte ao usuario se deseja semantizar o projeto e sugira: sema iniciar
+
+## Exemplos de arquivos .sema (referencia de formato)
+
+### 1. Task simples com testes
+```
+module exemplos.calculadora {
+  task somar {
+    input {
+      a: Numero required
+      b: Numero required
+    }
+    output {
+      resultado: Numero
+    }
+    rules {
+      a deve_ser numero_valido
+      b deve_ser numero_valido
+    }
+    effects {
+      auditoria operacao soma
+    }
+    guarantees {
+      resultado existe
+    }
+    error {
+      entrada_invalida: "Os valores precisam ser numericos."
+    }
+    tests {
+      caso "soma basica" {
+        given { a: 2  b: 3 }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+}
+```
+
+### 2. Entity + CRUD com route
+```
+module exemplos.crud.simples {
+  entity Produto {
+    fields {
+      id: Id
+      nome: Texto
+      preco: Decimal
+      ativo: Booleano
+    }
+  }
+
+  task criar_produto {
+    input {
+      nome: Texto required
+      preco: Decimal required
+    }
+    output {
+      produto: Produto
+    }
+    rules {
+      nome deve_ser preenchido
+      preco deve_ser positivo
+    }
+    effects {
+      persistencia Produto
+      auditoria produto_criado
+    }
+    guarantees {
+      produto existe
+    }
+    tests {
+      caso "cria produto" {
+        given { nome: "Caneca"  preco: 39.9 }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+
+  route produtos {
+    metodo: POST
+    caminho: /produtos
+    task: criar_produto
+    finalidade: cadastro_produto
+    input { nome: Texto  preco: Decimal }
+    output { produto: Produto }
+  }
+}
+```
+
+### 3. Cadastro com validacoes e unicidade
+```
+module exemplos.cadastro.usuario {
+  entity Usuario {
+    fields {
+      id: Id
+      nome: Texto
+      email: Email
+      ativo: Booleano
+    }
+  }
+
+  task criar_usuario {
+    input {
+      nome: Texto required
+      email: Email required
+    }
+    output {
+      usuario: Usuario
+    }
+    rules {
+      nome deve_ser preenchido
+      email deve_ser email_valido
+      email deve_ser unico em Usuario.email
+    }
+    effects {
+      persistencia Usuario
+      evento usuario_criado
+      auditoria cadastro_usuario
+    }
+    guarantees {
+      usuario existe
+      persistencia concluida
+    }
+    error {
+      email_duplicado: "Ja existe usuario com este email."
+      entrada_invalida: "Os dados informados nao atendem as regras."
+    }
+    tests {
+      caso "cria usuario valido" {
+        given { nome: "Ana"  email: "ana@empresa.com" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+}
+```
+
+### 4. Pagamento com state e flow
+```
+module exemplos.pagamento {
+  task processar_pagamento {
+    input {
+      pagamento_id: Id required
+      valor: Decimal required
+      token: Texto required
+    }
+    output {
+      pagamento: Pagamento
+      status: StatusPagamento
+    }
+    rules {
+      valor > 0
+      token deve_ser valido
+    }
+    effects {
+      consulta gateway_pagamento criticidade = alta
+      persistencia Pagamento criticidade = alta
+      evento pagamento_autorizado criticidade = media
+      auditoria pagamento criticidade = alta
+    }
+    state ciclo_pagamento {
+      transitions {
+        PENDENTE -> AUTORIZADO
+        AUTORIZADO -> PROCESSADO
+      }
+    }
+    guarantees {
+      pagamento existe
+      status em [AUTORIZADO, PROCESSADO]
+    }
+    error {
+      autorizacao_negada: "Recusado pelo gateway."
+      timeout_gateway: "Gateway nao respondeu."
+    }
+    tests {
+      caso "pagamento autorizado" {
+        given { pagamento_id: "pag_1"  valor: 199.9  token: "tok_ok" }
+        expect { sucesso: verdadeiro }
+      }
+      caso "pagamento recusado" {
+        given { pagamento_id: "pag_err"  valor: 10  token: "tok_recusado" }
+        expect { sucesso: falso }
+        error { tipo: "autorizacao_negada" }
+      }
+    }
+  }
+
+  flow orquestracao_pagamento {
+    pagamento_id: Id
+    valor: Decimal
+    token: Texto
+    etapa autorizar usa processar_pagamento com pagamento_id = pagamento_id, valor = valor, token = token em_sucesso confirmar em_erro registrar_falha
+    etapa confirmar usa confirmar_pagamento com pagamento_id = pagamento_id depende_de autorizar
+    etapa registrar_falha usa registrar_timeout_pagamento com pagamento_id = pagamento_id depende_de autorizar
+  }
+}
+```
+
+### 5. Tratamento de erro com flow ramificado
+```
+module exemplos.tratamento.erro {
+  task executar_operacao_sensivel {
+    input {
+      chave: Texto required
+    }
+    output {
+      protocolo: Id
+    }
+    rules {
+      chave deve_ser preenchida
+    }
+    effects {
+      consulta cofre
+      auditoria falha_operacao_sensivel
+    }
+    guarantees {
+      protocolo existe
+    }
+    error {
+      acesso_negado: "A chave nao tem permissao."
+      recurso_indisponivel: "Servico temporariamente indisponivel."
+    }
+    tests {
+      caso "falha por acesso negado" {
+        given { chave: "sem_permissao" }
+        expect { sucesso: falso }
+        error { tipo: "acesso_negado" }
+      }
+    }
+  }
+
+  flow resposta_segura {
+    chave: Texto
+    etapa tentar usa executar_operacao_sensivel com chave = chave em_sucesso concluir em_erro registrar_falha por_erro acesso_negado = tratar_acesso_negado, recurso_indisponivel = agendar_retentativa
+    etapa tratar_acesso_negado usa responder_acesso_negado com chave = chave depende_de tentar
+    etapa agendar_retentativa usa responder_retentativa com chave = chave depende_de tentar
+    etapa registrar_falha usa registrar_auditoria_falha com chave = chave depende_de tentar
+    etapa concluir usa registrar_sucesso com protocolo = tentar.protocolo depende_de tentar
+  }
+}
+```

package/AGENT_CONTEXT_PACK.json

@@ -0,0 +1,164 @@
+{
+  "nome": "Agent Context Pack",
+  "versao": 1,
+  "objetivo": "Dar a agentes IA uma entrada curta, estruturada e auditavel antes de abrir codigo cru ou inventar contexto.",
+  "ordemLeitura": [
+    "llms.txt",
+    "AGENT_CONTEXT_PACK.json",
+    "SEMA_BRIEF.micro.txt",
+    "SEMA_INDEX.json",
+    "AGENTS.md",
+    "exemplos/"
+  ],
+  "regrasObrigatorias": [
+    "Contrato vem antes da acao.",
+    "Leia AGENTS.md antes de editar codigo, contrato, docs operacionais, release ou deploy.",
+    "Use exemplos oficiais antes de criar ou corrigir sintaxe .sema.",
+    "Use SEMA_INDEX.json para escolher contrato, modulo e arquivos provaveis antes de abrir codigo cru.",
+    "Valide .sema alterado e rode drift antes de concluir.",
+    "Quando faltar contrato aplicavel, crie ou edite o contrato antes do codigo."
+  ],
+  "proibicoes": [
+    "Nao inventar sintaxe Sema fora da gramatica e dos exemplos oficiais.",
+    "Nao tratar README, texto livre ou codigo como fonte superior ao contrato.",
+    "Nao sincronizar segredos, .env, node_modules, builds, caches, uploads ou artefatos privados fora do escopo.",
+    "Nao publicar, deployar ou remover capacidade sem contrato, drift e verificacao.",
+    "Nao misturar repositorio publico e privado sem conferir docs de repositorios e AGENTS.md."
+  ],
+  "prioridades": [
+    "Menor artefato suficiente primeiro.",
+    "Contrato, indice e AGENTS antes de codigo cru.",
+    "Exemplos oficiais antes de nova sintaxe.",
+    "Diagnostico estruturado antes de opiniao livre.",
+    "Se risco ou escopo estiver ambigui, parar e pedir contrato/contexto."
+  ],
+  "fontes": [
+    {
+      "caminho": "llms.txt",
+      "tipo": "entrypoint",
+      "prioridade": 1,
+      "obrigatorio": true,
+      "quandoUsar": "sempre no primeiro contato com o projeto",
+      "incluirTextoBrutoQuando": "a IA precisa de orientacao compacta para operar o repositorio"
+    },
+    {
+      "caminho": "AGENT_CONTEXT_PACK.json",
+      "tipo": "entrypoint",
+      "prioridade": 2,
+      "obrigatorio": true,
+      "quandoUsar": "sempre antes de decidir quais documentos ou exemplos abrir",
+      "incluirTextoBrutoQuando": "a IA precisa auditar regras, proibicoes, prioridades e fontes de verdade"
+    },
+    {
+      "caminho": "SEMA_BRIEF.micro.txt",
+      "tipo": "resumo",
+      "prioridade": 3,
+      "obrigatorio": true,
+      "quandoUsar": "IA pequena, onboarding, chat remoto ou primeiro triage",
+      "incluirTextoBrutoQuando": "a tarefa cabe em contexto curto"
+    },
+    {
+      "caminho": "SEMA_BRIEF.curto.txt",
+      "tipo": "resumo",
+      "prioridade": 4,
+      "obrigatorio": true,
+      "quandoUsar": "IA media, mudanca pequena ou review rapido",
+      "incluirTextoBrutoQuando": "o modulo alvo ainda nao esta claro pelo micro"
+    },
+    {
+      "caminho": "SEMA_INDEX.json",
+      "tipo": "indice",
+      "prioridade": 5,
+      "obrigatorio": true,
+      "quandoUsar": "antes de abrir codigo cru ou escolher contrato alvo",
+      "incluirTextoBrutoQuando": "a IA precisa mapear modulos, lacunas, riscos ou arquivos provaveis"
+    },
+    {
+      "caminho": "AGENTS.md",
+      "tipo": "operacional",
+      "prioridade": 6,
+      "obrigatorio": true,
+      "quandoUsar": "antes de editar codigo, contrato, docs operacionais, release ou deploy",
+      "incluirTextoBrutoQuando": "a IA precisa confirmar regras locais obrigatorias e prioridades do projeto"
+    },
+    {
+      "caminho": "exemplos/",
+      "tipo": "exemplos",
+      "prioridade": 7,
+      "obrigatorio": true,
+      "quandoUsar": "antes de criar ou corrigir arquivo .sema, profile, Author, workflow, ops, game, legal ou research",
+      "incluirTextoBrutoQuando": "a IA vai escrever sintaxe Sema ou comparar um contrato com formato oficial"
+    },
+    {
+      "caminho": "docs/AGENT_STARTER.md",
+      "tipo": "docs",
+      "prioridade": 8,
+      "obrigatorio": false,
+      "quandoUsar": "onboarding de agente novo ou explicacao curta do fluxo",
+      "incluirTextoBrutoQuando": "o agente remoto nao conhece Sema ainda"
+    },
+    {
+      "caminho": "docs/sintaxe.md",
+      "tipo": "docs",
+      "prioridade": 9,
+      "obrigatorio": false,
+      "quandoUsar": "duvida de gramatica, blocos ou formato do DSL",
+      "incluirTextoBrutoQuando": "a IA vai editar contrato e os exemplos nao bastam"
+    },
+    {
+      "caminho": "contratos/",
+      "tipo": "contrato",
+      "prioridade": 10,
+      "obrigatorio": true,
+      "quandoUsar": "antes de qualquer implementacao ou alteracao de comportamento",
+      "incluirTextoBrutoQuando": "a tarefa toca uma capacidade governada por contrato"
+    }
+  ],
+  "exemplosOficiais": [
+    "exemplos/calculadora.sema",
+    "exemplos/pagamento.sema",
+    "exemplos/profile_software.sema",
+    "exemplos/profile_workflow_n8n.sema",
+    "exemplos/profile_ops.sema",
+    "exemplos/profile_game.sema",
+    "exemplos/profile_legal.sema",
+    "exemplos/profile_research.sema",
+    "exemplos/author_obra_comum.sema"
+  ],
+  "textoBrutoSobDemanda": {
+    "llms.txt": "a IA precisa de orientacao compacta para operar o repositorio",
+    "AGENT_CONTEXT_PACK.json": "a IA precisa auditar regras, proibicoes, prioridades e fontes de verdade",
+    "SEMA_BRIEF.micro.txt": "a tarefa cabe em contexto curto",
+    "SEMA_BRIEF.curto.txt": "o modulo alvo ainda nao esta claro pelo micro",
+    "SEMA_INDEX.json": "a IA precisa mapear modulos, lacunas, riscos ou arquivos provaveis",
+    "AGENTS.md": "a IA precisa confirmar regras locais obrigatorias e prioridades do projeto",
+    "exemplos/": "a IA vai escrever sintaxe Sema ou comparar um contrato com formato oficial",
+    "docs/AGENT_STARTER.md": "o agente remoto nao conhece Sema ainda",
+    "docs/sintaxe.md": "a IA vai editar contrato e os exemplos nao bastam",
+    "contratos/": "a tarefa toca uma capacidade governada por contrato"
+  },
+  "guiaPorCapacidade": {
+    "pequena": [
+      "agent-context-pack.json",
+      "resumo.micro.txt",
+      "briefing.min.json",
+      "resumo.curto.txt"
+    ],
+    "media": [
+      "agent-context-pack.json",
+      "resumo.curto.txt",
+      "briefing.min.json",
+      "drift.json",
+      "resumo.md"
+    ],
+    "grande": [
+      "agent-context-pack.json",
+      "README.md",
+      "resumo.md",
+      "briefing.json",
+      "drift.json",
+      "ir.json",
+      "ast.json"
+    ]
+  }
+}

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Sema
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+