Ferramenta hystore

@hystudios/hystore edita o tema em código da sua loja no seu computador, com a IA que você já usa (Claude Code, Cursor, Codex, Copilot) e com git. Precisa só do Node.js 18.17 ou mais novo.

npx @hystudios/hystore login
npx @hystudios/hystore theme pull
npx @hystudios/hystore theme dev

Passo a passo

1. Entre na sua loja

npx @hystudios/hystore login

1. A ferramenta mostra um código de 8 letras e abre o painel no navegador.
2. Confira se o código no painel é o mesmo do terminal.
3. Escolha a loja e o que a ferramenta pode fazer (ler, editar o rascunho, pedir publicação).
4. Clique em Autorizar. O terminal mostra a loja conectada.

Não há token para copiar nem colar. O código vale 10 minutos e uma vez só.

2. Baixe o tema

mkdir minha-loja && cd minha-loja
npx @hystudios/hystore theme pull

A pasta fica assim:

minha-loja/
  theme.json
  layout/theme.liquid
  pages/home.liquid
  sections/hero.liquid
  styles/theme.css
  locales/pt.json  en.json  es.json
  assets/logo.webp
  apps/roleta/index.html
  AGENTS.md                         regras e guia para a IA
  CLAUDE.md                         o mesmo, para o Claude Code
  .cursor/rules/hystore-theme.mdc   para o Cursor
  .claude/skills/hystore-theme/SKILL.md

Uma loja sem tema? Use theme new para começar pelo tema Base:

npx @hystudios/hystore theme new minha-loja

3. Deixe a prévia rodando

npx @hystudios/hystore theme dev

Ela confere e envia cada arquivo que você grava e abre a prévia no endereço da loja, que recarrega sozinha. Deixe esse terminal aberto enquanto trabalha.

4. Edite, você ou a sua IA

Abra a pasta no editor e peça para a IA, por exemplo: "Faz um banner de Black Friday no topo da home, nas cores da loja, com textos em pt, en e es." Ela lê o AGENTS.md (ou o CLAUDE.md) e segue as regras do tema.

5. Confira

npx @hystudios/hystore theme check

Mesmas regras do servidor, na sua máquina. Um erro mostra o arquivo, a linha e o motivo:

  x sections/banner.liquid:3  Event attributes (onclick, onload...) are not allowed. Use data-hystore-* components. (html_event_handler)

6. Peça a publicação

npx @hystudios/hystore theme publish --note "Banner da Black Friday"

Isso cria um pedido de publicação. Quem tem a permissão Publicar o tema abre Personalização > Tema em código > Pedidos de publicação, vê o que mudou e aprova.

7. Guarde no git

git init && git add . && git commit -m "Tema da loja"

Nenhum arquivo da pasta tem token ou chave: ela pode ir para um repositório. A ferramenta já deixa no .gitignore o que não deve ir (.hystore/, com o estado da sincronização, e as cópias *.remote).

Comandos

Opções: --dir <pasta>, --force, --no-open, --lang pt|en|es. hystore pull funciona como hystore theme pull.

A sessão

• Dura 30 dias e se renova sozinha. Aparece em Personalização > Acesso ao tema > Sessões conectadas, onde pode ser desconectada.
• Fica na sua pasta de usuário (~/.config/hystore, ou %APPDATA%\hystore no Windows), que só você lê. Nunca na pasta do tema.
• A cada login novo, o dono da loja recebe um e-mail com o link para desconectar.

Conflitos

Cada envio leva a versão de cada arquivo que você baixou por último. Se alguém mudou esse arquivo no painel nesse meio tempo, o envio é recusado em vez de passar por cima. Rode theme pull:

• o que mudou só na loja chega;
• o que mudou só aqui fica;
• um arquivo mudado nos dois lugares mantém o seu, com a cópia da loja ao lado como <arquivo>.remote. Junte, apague o .remote e envie de novo.

theme push --force grava por cima da versão da loja; theme pull --force deixa a pasta igual à loja.

Em CI (GitHub Actions)

Para CI, crie uma chave em Personalização > Acesso ao tema > Criar chave (escopos ler e editar, e pedir publicação se o CI for pedir) e guarde nos segredos do repositório como HYSTORE_THEME_TOKEN. A ferramenta usa essa variável no lugar do login.

name: tema
on:
  push:
    branches: [main]
jobs:
  enviar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx @hystudios/hystore theme check
      - run: npx @hystudios/hystore theme push --force
        env:
          HYSTORE_THEME_TOKEN: ${{ secrets.HYSTORE_THEME_TOKEN }}
      - run: npx @hystudios/hystore theme publish --note "Commit ${{ github.sha }}"
        env:
          HYSTORE_THEME_TOKEN: ${{ secrets.HYSTORE_THEME_TOKEN }}

• --force: no CI o git é a fonte da verdade, e a pasta clonada não tem o estado da última sincronização (.hystore/, que fica fora do git). O envio grava a pasta por cima do rascunho.
• O último passo só cria o pedido: a loja muda quando alguém aprova no painel.

Segurança

• Publicar é sempre um pedido aprovado no painel.
• A ferramenta só lê e grava arquivos do tema na pasta; os outros ficam como estão.
• Imagens e fontes só são baixadas do endereço da Hystore e conferidas pelo hash.