@jevaas/cli

CLI do JEVaaS: julga, publica contrato, lê recibo e calibração de linha de comando. Sem framework — parseArgs do Node basta, como no CLI do RAGaaS.

npm i -g @jevaas/cli
jevaas login jev_sk_…        # grava em ~/.jevaas/config.json (chmod 600)
jevaas judge decisao.json

Comandos

autenticação
  login <jev_sk_…> [--url <base>]   grava a chave em ~/.jevaas/config.json (chmod 600)
  logout                              apaga a config

contratos
  contracts list                      lista os contratos (última versão de cada)
  contracts get <id>                  última versão de um contrato
  contracts versions <id>             histórico de versões
  contract create <arq.yaml|json>     publica a versão 1 (valida no serviço; §5)
  contract promote <id> <versão>      torna a versão vigente (admin)
  contract mode <id> shadow|enforce   sombra mede; enforce autoriza (admin)

decisão
  judge <arq.json> [--dry-run]        julga {contract, state, …} de um arquivo
  receipts [--contract <id>] [--route <r>]   lista recibos do inquilino
  receipt label <id> <rótulo>         rótulo humano — insumo da calibração
  calibration <contract-id>           acerto × confiança por faixa e versão

Flags globais: --url <base> · --json (saída crua).

Julgar

O arquivo é o corpo do §4.1 — só os campos documentados atravessam (contract, contract_version, state, state_version, operation, decision_id, trace_id); qualquer outro é ignorado, como o serviço já faz com tenant_id (§1).

{
  "contract": "ticket-router",
  "state": { "ticket": { "messages": [{ "author": "customer", "text": "…" }] } },
  "state_version": "run_184:step_7"
}

$ jevaas judge decisao.json
ticket-router@3  enforce  internal_write
status decided · rota auto · allow support:route
confiança decisiva 0.93 · barra 0.75 · piso 0.70 · regra 0
decisivo: fila_principal = suporte
recibo rcp_01J9Z… · 1630ms · 40µUSD
AUTORIZADO: Age, dentro do `allow`.

Quando a rota não autoriza, a saída diz isso em uma linha — NÃO AUTORIZADO A AGIR — Enfileire para uma pessoa; não age. O julgamento em modo sombra chega com enforced: false e não libera ação.

--dry-run resolve o corpo e imprime o request sem chamar a API (nem exigir chave): serve para revisar o julgamento no CI antes de gastar token.

Contratos

contract create aceita JSON e YAML. O leitor de YAML é um subconjunto fail-closed — mapas aninhados, sequências em bloco (de escalares e de mapas), coleções em linha, escalares, comentários e strings simples — e recusa o que muda o significado em silêncio (âncoras, blocos literais |/>, tags, múltiplos documentos, tabulação na indentação, chave repetida). Um contrato mal lido governaria produção; um recusado não. Arquivos .json são lidos como JSON.

# ticket-router.yaml
id: ticket-router
description: Roteia tickets de suporte
owner: [email protected]
action_class: internal_write
primary_question: fila_principal
questions:
  fila_principal:
    type: choice
    instructions: Qual equipe deve tratar a solicitação principal?
    criteria:
      vendas: Pedido comercial, proposta ou renovação.
      suporte: Dúvida de uso, incidente ou reclamação técnica.
      indeterminado: Evidência insuficiente para escolher.
routes:
  - when:
      question: fila_principal
      equals: suporte
    route: auto
    allow: support:route
default_route: human_review

Mudança de regra é versão nova (contracts + contract create não editam a anterior — PUT /contracts/{id} faz isso pela API), e contract promote decide qual versão está vigente. Publicar conteúdo decisório idêntico devolve 409 version_conflict.

Credenciais e ambiente

Precedência: --url → JEVAAAS_URL → ~/.jevaas/config.json para a base, e JEVAAAS_API_KEY → config para a chave. JEVAAAS_TIMEOUT_S ajusta o timeout por request. Nenhum valor de chave é impresso pela CLI.

Erros

Erro da API é reportado no formato do serviço e encerra com código 1:

$ jevaas contracts get nao-existe
API 404: contrato não encontrado (request req_abc123)

Licença

MIT © Vertikon