# 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](https://nodejs.org) 18.17 ou mais novo. ```bash npx @hystudios/hystore login npx @hystudios/hystore theme pull npx @hystudios/hystore theme dev ``` > [!TIP] > Quer usar sempre? Instale uma vez com `npm install -g @hystudios/hystore` e > troque `npx @hystudios/hystore` por `hystore` nos comandos. ## Passo a passo ### 1. Entre na sua loja ```bash 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 ```bash mkdir minha-loja && cd minha-loja npx @hystudios/hystore theme pull ``` A pasta fica assim: ```text 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: ```bash npx @hystudios/hystore theme new minha-loja ``` ### 3. Deixe a prévia rodando ```bash 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 ```bash npx @hystudios/hystore theme check ``` Mesmas regras do servidor, na sua máquina. Um erro mostra o arquivo, a linha e o motivo: ```text 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 ```bash 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 ```bash 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 | Comando | O que faz | |---|---| | `login` | entra com o código aprovado no painel | | `logout` | encerra a sessão também no servidor | | `whoami` | mostra a loja e as permissões | | `theme pull` | baixa o rascunho para a pasta, com imagens, fontes e os arquivos para IA | | `theme push` | confere a pasta e envia o que mudou desde a última sincronização | | `theme dev` | envia a cada gravação e abre a prévia, que recarrega sozinha | | `theme check` | confere na sua máquina, com as mesmas regras do servidor | | `theme open` | abre um link de prévia do rascunho (24 horas) | | `theme publish` | pede a publicação (`--note "..."`); aprovada no painel | | `theme versions` | lista as últimas 30 versões publicadas | | `theme rollback ` | traz a versão n de volta para o rascunho (`--yes` pula a pergunta) | | `theme new [pasta]` | cria uma pasta a partir do tema Base | Opções: `--dir `, `--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 `.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. ```yaml .github/workflows/tema.yml 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.