Herramienta hystore

@hystudios/hystore edita el tema en código de tu tienda en tu computadora, con la IA que ya usas (Claude Code, Cursor, Codex, Copilot) y con git. Solo necesita Node.js 18.17 o más nuevo.

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

Paso a paso

1. Entra a tu tienda

npx @hystudios/hystore login

1. La herramienta muestra un código de 8 letras y abre el panel en el navegador.
2. Revisa que el código en el panel sea el mismo de la terminal.
3. Elige la tienda y lo que la herramienta puede hacer (leer, editar el borrador, pedir publicación).
4. Haz clic en Autorizar. La terminal muestra la tienda conectada.

No hay token para copiar ni pegar. El código vale 10 minutos y una sola vez.

2. Descarga el tema

mkdir mi-tienda && cd mi-tienda
npx @hystudios/hystore theme pull

La carpeta queda así:

mi-tienda/
  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                         reglas y guía para la IA
  CLAUDE.md                         lo mismo, para Claude Code
  .cursor/rules/hystore-theme.mdc   para Cursor
  .claude/skills/hystore-theme/SKILL.md

¿Una tienda sin tema? Usa theme new para empezar por el tema Base:

npx @hystudios/hystore theme new mi-tienda

3. Deja la vista previa corriendo

npx @hystudios/hystore theme dev

Revisa y envía cada archivo que guardas y abre la vista previa en la dirección de la tienda, que se recarga sola. Deja esa terminal abierta mientras trabajas.

4. Edita, tú o tu IA

Abre la carpeta en el editor y pídele a la IA, por ejemplo: "Haz un banner de Black Friday arriba en el inicio, en los colores de la tienda, con textos en pt, en y es." Lee el AGENTS.md (o el CLAUDE.md) y sigue las reglas del tema.

5. Revisa

npx @hystudios/hystore theme check

Las mismas reglas del servidor, en tu máquina. Un error muestra el archivo, la línea y el motivo:

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

6. Pide la publicación

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

Esto crea un pedido de publicación. Quien tiene el permiso Publicar el tema abre Personalización > Tema en código > Pedidos de publicación, ve lo que cambió y aprueba.

7. Guárdalo en git

git init && git add . && git commit -m "Tema de la tienda"

Ningún archivo de la carpeta tiene token ni llave: puede ir a un repositorio. La herramienta ya deja en el .gitignore lo que no debe ir (.hystore/, con el estado de la sincronización, y las copias *.remote).

Comandos

Opciones: --dir <carpeta>, --force, --no-open, --lang pt|en|es. hystore pull funciona como hystore theme pull.

La sesión

• Dura 30 días y se renueva sola. Aparece en Personalización > Acceso al tema > Sesiones conectadas, donde se puede desconectar.
• Queda en tu carpeta de usuario (~/.config/hystore, o %APPDATA%\hystore en Windows), que solo tú lees. Nunca en la carpeta del tema.
• Por cada inicio de sesión nuevo, el dueño de la tienda recibe un correo con el enlace para desconectarlo.

Conflictos

Cada envío lleva la versión de cada archivo que descargaste por última vez. Si alguien cambió ese archivo en el panel mientras tanto, el envío se rechaza en vez de pisarlo. Ejecuta theme pull:

• lo que cambió solo en la tienda llega;
• lo que cambió solo aquí se queda;
• un archivo cambiado en los dos lugares mantiene el tuyo, con la copia de la tienda al lado como <archivo>.remote. Junta, borra el .remote y envía de nuevo.

theme push --force escribe encima de la versión de la tienda; theme pull --force deja la carpeta igual a la tienda.

En CI (GitHub Actions)

Para CI, crea una llave en Personalización > Acceso al tema > Crear llave (alcances leer y editar, y pedir publicación si el CI la va a pedir) y guárdala en los secretos del repositorio como HYSTORE_THEME_TOKEN. La herramienta usa esa variable en lugar del inicio de sesión.

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: en CI git es la fuente de la verdad, y la carpeta clonada no tiene el estado de la última sincronización (.hystore/, que queda fuera de git). El envío escribe la carpeta encima del borrador.
• El último paso solo crea el pedido: la tienda cambia cuando alguien lo aprueba en el panel.

Seguridad

• Publicar es siempre un pedido aprobado en el panel.
• La herramienta solo lee y escribe archivos del tema en la carpeta; los demás quedan como están.
• Las imágenes y fuentes solo se descargan de la dirección de Hystore y se revisan por el hash.