Temas e CLI › CLI

O CLI de temas

O denaryx é o programa de linha de comando para quem cria temas de lojas na Denaryx: começa um tema a partir do Pilar, confere o código com o mesmo verificador da plataforma, envia e baixa os arquivos sem atropelar quem edita no painel, cria links de prévia e publica. Roda no seu computador e no CI.

npm install -g denaryx
denaryx login
denaryx tema init meu-tema
cd meu-tema
denaryx tema check
denaryx tema dev
denaryx tema push --novo "Tema da agência"
denaryx tema share --nome "Para o cliente" --congelar

Os comandos e as opções estão em Os comandos; o trabalho com a loja de verdade e a página que se atualiza a cada arquivo salvo, em Desenvolver com o tema dev; o uso no CI, em No CI e no GitHub; e o tema ligado a uma branch, atualizado a cada push sem CI, em O tema no GitHub.

Instalação

npm install -g denaryx

• Pede Node 22.12 ou mais novo.
• Um arquivo só, sem dependências. O pacote não instala nada além dele e não roda script na instalação. O verificador de temas e o Pilar vão dentro do arquivo, na versão do CLI.
• Sem instalar: npx denaryx@0.5.0 tema check. No CI, fixe a versão.
• Uma vez por dia, o CLI consulta o npm para avisar quando há versão nova. A consulta não leva nada de quem usa, e não acontece em CI, sem terminal, no --json nem com DENARYX_SEM_AVISOS=1.

Entrar numa loja

Há dois jeitos: pela sua conta, no seu computador, e pelo token de uma integração, no CI.

Pela sua conta

denaryx login

O CLI mostra um código e abre o painel em https://denaryx.com/painel/cli. Entre com a sua conta (se ainda não entrou), digite o código, confira que ele é o mesmo do terminal e de onde veio o pedido, escolha a loja e autorize. O terminal recebe o acesso e mostra a loja e o que você pode fazer nela:

Para entrar, abra https://denaryx.com/painel/cli e digite o código:

    BCDF-GHJK

Entrou na loja Loja Exemplo (loja-exemplo) como ana@agencia.com.br.

• Sem pedir token a ninguém. O acesso vale o que o seu papel na equipe vale nos temas: quem tem o papel Catálogo e vitrine envia e mostra a prévia; publica tema com código próprio quem é dono ou gerente, ou o Catálogo e vitrine quando o dono deixa. O papel é conferido a cada chamada: mudou, muda o acesso; saiu da equipe, ele deixa de valer.
• Só os temas. Nem pedidos, nem clientes, nem a conta de pagamento.
• 90 dias, com até 10 acessos por pessoa em cada loja. Os acessos ficam em Configurações › Integrações › Acessos pelo CLI, onde se revogam; denaryx logout revoga o seu na hora. A cada acesso autorizado, você recebe um e-mail.
• O código vale 10 minutos e uma vez. Nunca digite no painel um código que outra pessoa mandou: quem tem o acesso trabalha nos temas em seu nome.
• --nome dá ao aparelho o nome que aparece no painel (sem ele, o nome do computador). Num projeto com loja no denaryx.json, o painel já deixa a loja escolhida, e o acesso de outra loja é recusado.

Com o token de uma integração

O token de uma integração é o caminho do CI e de quem prefere um token: ela é criada no painel da loja em Configurações › Integrações por quem é dono ou gerente (ver Autenticação). Marque os escopos de temas:

O whoami vale com qualquer token, e o tema check sem --paginas nem chama a loja.

denaryx login --com-token

O CLI pergunta o token sem mostrá-lo na tela, ou o lê da entrada padrão (denaryx login --com-token < token.txt). Ele confere o token na loja e o guarda, como o acesso pela conta, num arquivo só do seu usuário:

• no Windows, %APPDATA%\denaryx\credenciais.json;
• nos outros sistemas, $XDG_CONFIG_HOME/denaryx/credenciais.json (ou ~/.config/denaryx/), com permissão 0600.

Cada loja tem a sua entrada, pela conta ou pelo token; --loja escolhe entre elas, e a primeira em que você entrou é a padrão. denaryx whoami mostra a loja, quem entrou (você ou a integração), os escopos e a validade. denaryx logout revoga o acesso pela conta; o token de integração ele só apaga desta máquina (para revogá-lo, use o painel).

O token nunca é argumento de linha de comando (ficaria no histórico do terminal) e nunca aparece numa mensagem do CLI. No CI, ele vem da variável DENARYX_TOKEN. O verificador recusa um token esquecido dentro do tema (secret_in_theme).

O projeto

Um projeto é uma pasta com o denaryx.json na raiz. O denaryx tema init cria um, com o Pilar dentro.

meu-tema/
  denaryx.json        a loja, o tema, os ambientes, a pasta do tema e o verificador (versionado)
  .denaryxignore      o que não vai para a loja (opcional)
  .denaryx/           o estado local do CLI (fora do Git)
  layout/ templates/ sections/ blocks/ snippets/ assets/ config/ locales/

{
  "loja": "minhaloja",
  "tema": "5b0d6f1e-2c3a-4d5e-8f90-1a2b3c4d5e6f",
  "pasta": ".",
  "ambientes": {
    "producao": {
      "loja": "cliente",
      "tema": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d"
    }
  },
  "verificador": {
    "regras": { "unused_snippet": "desligada" },
    "limites": { "js": 300 }
  }
}

Só as oito pastas do tema vão para a loja, e só os arquivos que a estrutura aceita (sem subpastas, nomes com letras, números, ponto, hífen e sublinhado). node_modules, src, o .git e o resto da pasta nunca saem da sua máquina. O CLI avisa o que ficou de fora e por quê, e não segue link simbólico para fora da pasta.

O .denaryxignore tem padrões como os do .gitignore, sobre os caminhos do tema: *.map, assets/rascunho-*, snippets/ (a pasta inteira), !snippets/manter.liquid (volta).

O .denaryx/ guarda o estado da sincronização (o checksum de cada arquivo na última vez que a pasta e a loja estavam iguais), por ambiente, e o tema de desenvolvimento do denaryx tema dev desta máquina. É desta máquina: o CLI põe um .gitignore dentro.

A sincronização

O push e o pull comparam três coisas: a pasta, a loja e o estado guardado.

• Sem estado (um clone novo do repositório, o CI): no push, a pasta é a verdade; no pull, a loja.
• Conflito: o CLI lista os arquivos e sai com o código 4. Resolva com pull (a loja), com push --forcar (a pasta vence) ou com pull --forcar (a loja vence).
• Ninguém atropela ninguém. Todo envio leva o checksum que foi lido de cada arquivo. Se alguém gravar no meio do envio, a loja recusa a parte que mudou, e o CLI sai com o código 4; o que já tinha ido fica, e o estado guarda.
• O mesmo conteúdo, em todo lugar. O texto vai sempre com fim de linha LF e sem BOM, e o checksum é calculado depois disso: o Windows, o CLI, o GitHub e a loja chegam ao mesmo conteúdo, sem diferença falsa. O init cria o .gitattributes com * text=auto eol=lf.
• A ordem do envio: primeiro as imagens, as fontes, os vídeos e os CSS e JS acima de 200 KB (até 20 arquivos e 25 MB por chamada); depois os textos, em lotes, com os snippets, os blocos e as seções antes dos templates e do layout; as remoções por último. As gravações vão uma de cada vez.
• Os limites da API: o CLI faz no máximo 3 chamadas ao mesmo tempo, espera o Retry-After quando a API pede (429 e 503) e repete a queda de rede com a mesma Idempotency-Key, para a gravação não acontecer duas vezes (ver Limites).
• Baixar: o tema próprio sem estado vem pelo zip, numa chamada; o resto, arquivo por arquivo, só o que mudou. Todo caminho que vem da loja é conferido, e nada é escrito fora da pasta do tema.
• Antes de enviar, o CLI roda o verificador e mostra os erros. Erro não impede de salvar (só de publicar), a menos do --estrito. A estrutura impede: a loja não grava um tema com arquivo fora das pastas.

Nada do que o CLI grava aparece na vitrine antes da publicação.

Saída e códigos de saída

O resultado vai para a saída padrão, e o andamento, os avisos e os erros para a saída de erro: denaryx tema check --json > problemas.json guarda só o JSON. --json dá o resultado de qualquer comando em JSON; o erro vem como { "error": { "code", "message", "details", "exit_code" } } e, quando veio da API, com o status, o request_id e, se houver, os conflicts e os problems. --detalhes mostra cada chamada à API com o Denaryx-Request-Id, que é o que o suporte pede. --sem-cor (ou a variável NO_COLOR) tira as cores.

Sem terminal, o CLI não pergunta nada: o que pede confirmação (publish, delete) precisa do --sim.

Variáveis de ambiente

Dados e licença

O CLI guarda as credenciais só na sua máquina e manda à Denaryx o necessário para cada comando. Não há telemetria: a única informação de uso é o User-Agent de cada chamada (denaryx-cli/<versão> node/<versão> <sistema>).

O uso é gratuito com lojas hospedadas na Denaryx, nos termos do LICENCA.txt que vai no pacote. O Pilar que o init traz pode ser usado e modificado só em lojas na Denaryx (o LICENCA.txt do projeto). Os componentes de código aberto que vão dentro do CLI estão no AVISOS-DE-TERCEIROS.txt.