# 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](https://nodejs.org) 18.17 o más nuevo. ```bash npx @hystudios/hystore login npx @hystudios/hystore theme pull npx @hystudios/hystore theme dev ``` > [!TIP] > ¿La usas todos los días? Instálala una vez con > `npm install -g @hystudios/hystore` y cambia `npx @hystudios/hystore` por > `hystore` en los comandos. ## Paso a paso ### 1. Entra a tu tienda ```bash 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 ```bash mkdir mi-tienda && cd mi-tienda npx @hystudios/hystore theme pull ``` La carpeta queda así: ```text 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: ```bash npx @hystudios/hystore theme new mi-tienda ``` ### 3. Deja la vista previa corriendo ```bash 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 ```bash 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: ```text x sections/banner.liquid:3 Event attributes (onclick, onload...) are not allowed. Use data-hystore-* components. (html_event_handler) ``` ### 6. Pide la publicación ```bash 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 ```bash 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 | Comando | Qué hace | |---|---| | `login` | entra con el código aprobado en el panel | | `logout` | cierra la sesión también en el servidor | | `whoami` | muestra la tienda y los permisos | | `theme pull` | descarga el borrador a la carpeta, con imágenes, fuentes y los archivos para IA | | `theme push` | revisa la carpeta y envía lo que cambió desde la última sincronización | | `theme dev` | envía en cada guardado y abre la vista previa, que se recarga sola | | `theme check` | revisa en tu máquina, con las mismas reglas del servidor | | `theme open` | abre un enlace de vista previa del borrador (24 horas) | | `theme publish` | pide la publicación (`--note "..."`); se aprueba en el panel | | `theme versions` | lista las últimas 30 versiones publicadas | | `theme rollback ` | trae la versión n de vuelta al borrador (`--yes` salta la pregunta) | | `theme new [carpeta]` | crea una carpeta a partir del tema Base | Opciones: `--dir `, `--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 `.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. ```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`: 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.