shade-cli

O comando shade: cria, ensaia, testa, empacota e envia robôs da ShadeOne escritos com o shade-sdk. O ciclo local roda sem conta; auth, deploy e releases falam com a plataforma pela chave de API. Nunca importa o runtime no próprio processo: o projeto roda em subprocesso, no venv dele (uv run na pasta), com o shade-sdk que ele fixa.

uv tool install shade-cli
shade init cadastro-erp          # starter de produção (--minimo para o enxuto)
cd cadastro-erp
uv run playwright install chromium
shade test                       # lint de contrato + pytest do projeto
shade run                        # ensaio: para antes de cada efetivar()
shade build                      # artefato determinístico em .shade/build/

Comandos

Com a chave de API

SHADE_API_KEY e SHADE_URL vencem o keyring (o caminho do CI). A chave nunca é argumento, nunca vai para arquivo e sai redigida de todo texto. http:// só para localhost.

O deploy é idempotente: o mesmo código dá o mesmo sha256, e o servidor devolve a release que já existe. Se a CLI cair no meio, repetir shade deploy (ou shade releases show <id> --esperar) retoma a mesma versão. O prazo da espera (10 min) sai 6 com esse comando.

Tudo o que a CLI escreve num projeto fica em .shade/ (que se ignora sozinho no git): o git status do projeto continua limpo depois de qualquer comando, menos o init.

CI

A mesma sequência em qualquer CI: instalar a CLI numa versão exata, shade test, shade deploy. A chave vem de SHADE_API_KEY, num segredo do CI e no env do job, nunca em argumento nem em arquivo. Sem terminal a CLI nunca pergunta (--criar diz que o robô novo é de propósito), e o --json põe o resultado no stdout. A release fica aguardando a aprovação de uma pessoa: o CI não ativa nada. A saída 6 (prazo da espera) não é falha: a release segue no servidor e o erro.recuperacao do JSON traz shade releases show <id> --esperar.

GitHub. A Action shade-deploy (.github/actions/shade-deploy/) roda essa sequência e devolve os outputs release_id, project_sha256 e estado, lidos do JSON. O shade init já gera o workflow com ela (job publicar, na branch padrão):

- uses: SamuelPerroni/shade-one/.github/actions/shade-deploy@cli-v0.1.6
  env:
    SHADE_API_KEY: ${{ secrets.SHADE_API_KEY }}
  with:
    versao-da-cli: "0.1.6"            # exata; sem latest
    # pasta: robos/cadastro            # onde está o shade.toml (padrão: a raiz)
    # url-da-plataforma: https://...   # sem ela, vale o SHADE_URL ou o padrão da CLI

O repositório do ShadeOne é privado: para outro repositório usar a Action, libere o acesso em Settings > Actions > General > Access do repositório do ShadeOne.

GitLab.

publicar:
  image: ghcr.io/astral-sh/uv:python3.14-bookworm
  script:
    - uv tool install shade-cli==0.1.6
    - export PATH="$(uv tool dir --bin):$PATH"
    - uv sync --locked
    - shade test --json
    - shade deploy --json --criar | tee deploy.json
    - python3 -c "import json; print(json.load(open('deploy.json'))['dados']['estado'])"
  variables:
    SHADE_API_KEY: $SHADE_API_KEY      # variável mascarada do projeto
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Azure Pipelines.

- script: |
    pip install uv
    uv tool install shade-cli==0.1.6
    export PATH="$(uv tool dir --bin):$PATH"
    uv sync --locked
    shade test --json
    shade deploy --json --criar
  displayName: Publicar o robô
  env:
    SHADE_API_KEY: $(SHADE_API_KEY)    # variável secreta: mapeie-a em env, o Azure não a expõe sozinho

Nos dois, o código de saída é o do shade: 1 gate reprovado, 3 chave, 6 prazo (retome com o comando do JSON), 7 rede. Trate o 6 como aviso se quiser o comportamento da Action.

--json e códigos de saída

Com --json, um documento no stdout; progresso e logs no stderr, redigidos:

{"versao": 1, "comando": "build", "ok": false, "dados": {},
 "erro": {"codigo": "lint_reprovado", "mensagem": "L3 robo.py:1 import fora do lock: yaml",
          "recuperacao": "corrija o que o lint aponta (shade test mostra a lista inteira)"}}

Lint de contrato

O lint não é controle de segurança: quem isola o robô é o executor da plataforma.

Desenvolvimento

cd cli && uv sync
uv run pytest -q -m "not starter"   # rápido
uv run pytest -q -m starter         # os starters de verdade: uv sync, Chromium, ~45 s

src/shade_cli/imagem.py é a cópia do requirements.lock da imagem do run: backend/tests/test_hu294_artefato_da_cli.py a confere, e confere que o artefato do shade build passa no ler() do backend.