{"id":50413557,"url":"https://github.com/say8425/hs-cli","last_synced_at":"2026-05-31T05:00:53.078Z","repository":{"id":360843911,"uuid":"1251967923","full_name":"say8425/hs-cli","owner":"say8425","description":"Hearthstone CLI for AI agents and humans. Decode deck codes, look up cards, query metadata via HearthstoneJSON","archived":false,"fork":false,"pushed_at":"2026-05-28T06:00:43.000Z","size":86,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T06:06:24.547Z","etag":null,"topics":["ai-agents","bun","citty","claude-code","claude-code-plugin","claude-code-skill","cli","deck-decoder","hearthstone","hearthstonejson","oxlint","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/say8425.png","metadata":{"files":{"readme":"README.es.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-28T04:22:10.000Z","updated_at":"2026-05-28T06:00:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/say8425/hs-cli","commit_stats":null,"previous_names":["say8425/hs-cli"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/say8425/hs-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/say8425%2Fhs-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/say8425%2Fhs-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/say8425%2Fhs-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/say8425%2Fhs-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/say8425","download_url":"https://codeload.github.com/say8425/hs-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/say8425%2Fhs-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33719601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","bun","citty","claude-code","claude-code-plugin","claude-code-skill","cli","deck-decoder","hearthstone","hearthstonejson","oxlint","typescript"],"created_at":"2026-05-31T05:00:52.387Z","updated_at":"2026-05-31T05:00:53.065Z","avatar_url":"https://github.com/say8425.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hs-cli\n\n[English](./README.md) · [한국어](./README.ko.md) · [日本語](./README.ja.md) · [中文](./README.zh.md) · **Español**\n\n[![Hearthstone](https://img.shields.io/badge/Hearthstone-F0A020?style=flat\u0026logo=battledotnet\u0026logoColor=white)](https://hearthstone.blizzard.com)\n[![Bun](https://img.shields.io/badge/Bun_1.3-000000?style=flat\u0026logo=bun\u0026logoColor=white)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/TypeScript_6-3178C6?style=flat\u0026logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org)\n[![citty](https://img.shields.io/badge/citty-111827?style=flat\u0026logo=unjs\u0026logoColor=ECDC5A)](https://github.com/unjs/citty)\n[![oxlint](https://img.shields.io/badge/oxlint-000000?style=flat\u0026logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI0OCIgaGVpZ2h0PSI0NiIgdmlld0JveD0iMCAwIDQ4IDQ2Ij48cGF0aCBkPSJNMzAuMzE2NCA2Ljc4ODc2QzMwLjMxNjQgOC4wMzgxNyAzMS4zMjg5IDkuMDUwNjMgMzIuNTc4MyA5LjA1MDYzSDQxLjE2MDVDNDIuMTY4NyA5LjA1MDYzIDQyLjY3MjcgMTAuMjY5OSA0MS45NTk3IDEwLjk4MDhMMzAuOTc3NyAyMS45NjI3QzMwLjU1MzQgMjIuMzg3MSAzMC4zMTQzIDIyLjk2MjIgMzAuMzE0MyAyMy41NjMzVjI3LjMxOEMzMC4zMTQzIDI4Ljg3OTcgMzEuODYzMSAyOS45NjMzIDMzLjIzMzIgMjkuMjE3OUMzNC42MjkxIDI4LjQ1OTcgMzUuOTI4IDI3LjU0MiAzNy4xMDIgMjYuNDkwOEMzNy41NjczIDI2LjA3NSAzOC4yODI1IDI2LjA3MDcgMzguNzI0MSAyNi41MTQ1TDQ2LjcyMjUgMzQuNTEyOUM0Ny4xNjQyIDM0Ljk1NDUgNDcuMTY2MyAzNS42NzE4IDQ2LjcwOTYgMzYuMDk4NEM0MC42NDM1IDQxLjc3NDYgMzIuNDkgNDUuMjUxNCAyMy41MjY1IDQ1LjI1MTRDMTQuNTYzIDQ1LjI1MTQgNi40MDk0NyA0MS43NzQ2IDAuMzQzMzMyIDM2LjA5ODRDLTAuMTEzMzUxIDM1LjY3MTggLTAuMTExMTk3IDM0Ljk1NDUgMC4zMzA0MDggMzQuNTEyOUw4LjMyODgzIDI2LjUxNDVDOC43NzA0NCAyNi4wNzI5IDkuNDg1NjMgMjYuMDc1IDkuOTUwOTIgMjYuNDkwOEMxMS4xMjQ5IDI3LjU0MiAxMi40MjM5IDI4LjQ1OTcgMTMuODE5OCAyOS4yMTc5QzE1LjE5MiAyOS45NjMzIDE2LjczODcgMjguODc5NyAxNi43Mzg3IDI3LjMxOFYyMy41NjMzQzE2LjczODcgMjIuOTYyMiAxNi40OTk2IDIyLjM4NzEgMTYuMDc1MiAyMS45NjI3TDUuMDkzMjcgMTAuOTgwOEM0LjM4MDI0IDEwLjI2NzcgNC44ODQzMiA5LjA1MDYzIDUuODkyNDcgOS4wNTA2M0gxNC40NzQ3QzE1LjcyNDEgOS4wNTA2MyAxNi43MzY2IDguMDM4MTcgMTYuNzM2NiA2Ljc4ODc2VjEuMTMxOTFDMTYuNzM2NiAwLjUwNzIwNiAxNy4yNDI4IDAuMDAwOTc2NTYyIDE3Ljg2NzUgMC4wMDA5NzY1NjJIMjkuMTc5QzI5LjgwMzcgMC4wMDA5NzY1NjIgMzAuMzEgMC41MDcyMDYgMzAuMzEgMS4xMzE5MVY2Ljc4ODc2SDMwLjMxNjRaIiBmaWxsPSIjMDBGN0YxIi8%2BPC9zdmc%2B)](https://oxc.rs)\n[![Claude Code](https://img.shields.io/badge/Claude_Code-Plugin-D77757?style=flat\u0026logo=anthropic\u0026logoColor=white)](https://code.claude.com)\n\n\u003e CLI de Hearthstone para agentes de IA y humanos. Decodifica códigos de mazo, busca cartas, consulta metadatos — sin API key. Construido sobre **Bun**.\n\n`hs-cli` es una herramienta CLI rápida y compatible con agentes que envuelve la fuente de datos pública [HearthstoneJSON](https://hearthstonejson.com/) y la librería `deckstrings` para proporcionar datos de mazos y cartas de Hearthstone con capacidad offline. La salida está diseñada para ser legible tanto por humanos como por agentes LLM (Claude Code, Codex, etc.) sin gastar tokens en JSON crudo.\n\n## Por qué existe\n\nEl ecosistema de Hearthstone tiene librerías y una API oficial de Blizzard, pero **ningún CLI de calidad de producción** y **ninguna integración lista para Claude Code**. Este proyecto cubre ese vacío. Las decisiones y compromisos están documentados en [CLAUDE.md](./CLAUDE.md).\n\n## Instalación\n\n### Homebrew (macOS / Linux — recomendado)\n\nNo requiere ningún runtime. Instala un binario autocontenido de ~64 MB.\n\n```bash\nbrew install say8425/tap/hs-cli\n```\n\nCompatible con darwin arm64/x64 y linux arm64/x64.\n\n### npm (cualquier SO con Node 24+)\n\n```bash\nnpm install -g @say8425/hs-cli\n```\n\nRequiere **Node 24+**. Bun no es necesario.\n\n### Binario precompilado\n\nDescarga el binario para tu plataforma desde [GitHub Releases](https://github.com/say8425/hs-cli/releases/latest) y dale permisos de ejecución:\n\n```bash\nchmod +x hs-\u003cplatform\u003e\nmv hs-\u003cplatform\u003e /usr/local/bin/hs\n```\n\nPlataformas disponibles: darwin arm64/x64, linux arm64/x64, windows x64. No requiere runtime.\n\n### Desde el código fuente (para desarrollo)\n\nRequiere **Bun 1.3+** ([instalar](https://bun.sh)).\n\n```bash\ngit clone https://github.com/say8425/hs-cli.git hs-cli\ncd hs-cli\nbun install\nbun run build\nbun link            # hace `hs` disponible globalmente\n```\n\nVerificar:\n\n```bash\nhs --version\nhs deck \"AAECAQcAA0VjgAEAAA==\"\n```\n\n### Instalar la skill de Claude Code\n\nEl CLI `hs` incluye la skill `hearthstone-deck`. Tras instalar el CLI:\n\n```bash\nhs skill install              # interactivo: elige agentes\nhs skill install --agent claude   # no interactivo\n```\n\nInstalación multi-agente vía [skills.sh](https://www.skills.sh/) (Cursor, Codex, Copilot, OpenCode):\n\n```bash\nnpx skills add say8425/hs-cli\n```\n\n## Uso\n\n### Decodificar un mazo\n\n```bash\nhs deck \u003cdeckcode\u003e\n```\n\n```\nClass:  Chamán (SHAMAN)\nFormat: Estándar\nDust:   15,760\nCards:  30\n\nMana Curve\n  1 █████ 4\n  2 ████████████ 10\n  ...\n```\n\nSímbolos de rareza: `★` Legendaria · `◆` Épica · `◇` Rara · `·` Común.\n\n### Buscar una carta\n\n```bash\nhs card 1124              # por dbfId\nhs card CS2_151           # por ID de carta\nhs card --search \"Zilliax\"\nhs card --search \"fuego\" --class MAGE --cost 3\nhs card --class MAGE --cost 3   # listar todas las cartas de Mago de coste 3 (sin --search)\n```\n\n### Consultar metadatos\n\n```bash\nhs meta classes           # las 14 clases\nhs meta sets              # todas las expansiones\nhs meta rarities          # FREE, COMMON, RARE, EPIC, LEGENDARY\nhs meta types             # MINION, SPELL, WEAPON, HERO, ...\n```\n\n### Meta en vivo (tasas de victoria, tiers, códigos de mazo)\n\n`hs meta archetypes` y `hs meta decks` muestran las tasas de victoria actuales del modo construido, tiers y códigos de mazo.\n\n```bash\nhs meta archetypes --game-format standard --rank legend --period past-7\nhs meta decks --rank top-2000-legend -f json\n```\n\nFlags: `--game-format standard|wild|twist`, `--rank legend|top-2000-legend|competitive|legend-diamond|diamond|platinum|bronze-gold|all`, `--period last-patch|past-3|past-7|past-20|current-season`, `--min-games N`, `--sort wilson|winrate|games`, `--limit N`. Las filas están ordenadas por el límite inferior de Wilson (no por la tasa de victoria bruta) y muestran una columna de ±margen de error.\n\nDatos: **Firestone** (firestoneapp.com), usado con permiso. Los códigos de mazo de `hs meta decks` se pueden pasar mediante pipe a `hs deck \u003ccode\u003e`.\n\n### Salida JSON\n\nAgrega `-f json` a cualquier comando:\n\n```bash\nhs deck \u003ccode\u003e -f json | jq '.cards | length'\nhs card --search \"Rey Exánime\" -f json | jq '.[].dbfId'\n```\n\n## Integración con agentes\n\nEste repositorio también funciona como **marketplace de Claude Code** y expone el [plugin `hs-cli`](./plugins/hs-cli/). Instálalo una vez y Claude Code aprenderá a usar el CLI automáticamente:\n\n```\n/plugin marketplace add say8425/hs-cli\n/plugin install hs-cli@say8425\n```\n\nPara desarrollo local:\n\n```bash\nclaude --plugin-dir ./plugins/hs-cli\n```\n\nEl plugin incluye la [skill `hearthstone-deck`](./plugins/hs-cli/skills/hearthstone-deck/SKILL.md), con namespace `/hs-cli:hearthstone-deck`.\n\nLuego pídele al agente cosas como:\n\n\u003e \"Analiza este mazo: AAECAQcAA0VjgAEAAA==\"\n\u003e\n\u003e \"Encuentra las cartas comunes entre estos dos mazos\"\n\u003e\n\u003e \"Recomienda cartas de 3 maná para sacerdote\"\n\nEl skill enseña al agente a:\n\n- Usar formato `table` por defecto (eficiente en tokens)\n- Recurrir a `json | jq` solo para extraer campos específicos\n- Traducir nombres de clases para usuarios multilingües\n- Detectar códigos de mazo antiguos/inválidos mediante marcadores `Unknown (id)` en la salida\n\n## Localización\n\n`hs` usa **enUS (inglés)** como configuración regional predeterminada. Puedes sobreescribirla con `-l, --locale \u003ccode\u003e` en cualquier comando, o exportar `HS_CLI_LOCALE` para un cambio permanente.\n\n```bash\nhs deck \u003ccode\u003e -l esES              # decodificar con nombres de carta en español\nhs card --search \"Zilliax\" -l esES  # buscar en datos de nombre en español\nhs card --search \"Zilliax\"          # búsqueda en inglés (enUS por defecto)\nexport HS_CLI_LOCALE=esES          # configuración permanente — todos los comandos en español\n```\n\n**Configuraciones regionales disponibles (14):** `enUS` `enGB` `frFR` `deDE` `koKR` `esES` `esMX` `ruRU` `zhTW` `zhCN` `itIT` `ptBR` `plPL` `jaJP` `thTH`\n\nLa entrada es flexible — `es`, `es-ES`, `es_ES` y `esES` se resuelven al mismo locale.\n\n**Orden de detección automática** (cuando se omite `-l`): `HS_CLI_LOCALE` → `LC_ALL` → `LC_MESSAGES` → `LANG` → `LANGUAGE` → `enUS`\n\nLos datos de cartas se almacenan en caché por locale en `~/.hs-cli/cards-\u003clocale\u003e.json` durante 24h.\n\n## Arquitectura\n\n```\nsrc/\n├── index.ts           # citty runMain\n├── commands/\n│   ├── deck.ts        # `hs deck \u003ccode\u003e` — defineCommand\n│   ├── card.ts        # `hs card \u003cq\u003e` / `--search`\n│   └── meta.ts        # `hs meta \u003ctype\u003e`\n├── services/\n│   ├── card-db.ts     # fetch HearthstoneJSON + caché en disco de 24h en ~/.hs-cli/\n│   ├── deck-decoder.ts # envoltorio de `deckstrings`, une con DB de cartas\n│   └── formatter.ts   # salida table / json\n└── types/index.ts\n```\n\n### Fuente de datos: HearthstoneJSON (no Battle.net API)\n\nVerificado el 2026-05-28 que HearthstoneJSON — que extrae datos directamente del `CardDefs.xml` del cliente del juego — es **más preciso** que la API oficial `/hearthstone/cards` de Blizzard:\n\n| | HearthstoneJSON | Battle.net API |\n|---|---|---|\n| Fuente | Extracto del cliente | API gateway (downstream de los datos del juego) |\n| Retraso de actualización | Horas después del parche | Más lento |\n| dbfIds faltantes | Muestra `Unknown (id)` | **Los descarta silenciosamente** |\n| Cobertura de Battlegrounds | Mejor | Tiene huecos |\n| Autenticación requerida | No | OAuth client credentials |\n| Funciona offline | Sí (caché de 24h) | No |\n\nLa integración con Battle.net API fue investigada y **deliberadamente no añadida** — no resuelve el problema de \"carta desconocida\" y solo añade complejidad. Ver [CLAUDE.md](./CLAUDE.md) para el razonamiento completo.\n\n## Cadena de herramientas\n\n| Herramienta | Propósito |\n|------|---------|\n| **Bun 1.3+** | Runtime + gestor de paquetes + runner de tests + bundler (reemplaza Node + pnpm + tsx + Vitest) |\n| **TypeScript 6** | Lenguaje fuente (tsc solo para typecheck — Bun ejecuta TS nativamente) |\n| **citty** | Parseo de argumentos CLI (unjs, type-inferred, ESM-first) |\n| **oxlint** | Linter (sin ESLint) — estricto en correctness/perf, solo arrow |\n| **oxfmt** | Formatter (sin Prettier) |\n| **bun:test** | Runner de tests con API compatible con Jest (sin Vitest/Jest/node:test) |\n| **deckstrings** | Codec oficial de HearthSim para códigos de mazo |\n\n## Desarrollo\n\n```bash\nbun run dev deck \u003ccode\u003e    # ejecuta vía Bun, sin build (TS nativo)\nbun test                   # todos los tests\nbun run lint               # oxlint\nbun run lint:fix           # auto-arreglo\nbun run fmt                # oxfmt write\nbun run fmt:check          # oxfmt check (CI)\nbun run typecheck          # tsc --noEmit\nbun run check              # lint + fmt:check + typecheck + test\nbun run build              # bun build → dist/ (minified)\n```\n\n## Roadmap\n\n### Phase 1 — ✅ completa\n\n- [x] `hs deck` — decodificar códigos de mazo\n- [x] `hs card` — individual + búsqueda\n- [x] `hs meta` — sets/classes/types/rarities\n- [x] Caché local, salida amigable para agentes, SKILL.md\n- [x] Nativo de Bun (sin dependencia de Node)\n\n### Phase 2 — planificada\n\n- [ ] `hs log parse` — parsear el `Power.log` de Hearthstone vía subproceso [python-hslog](https://github.com/HearthSim/python-hslog)\n- [ ] `hs log show \u003cmatch-id\u003e` — replay de partidas individuales\n- [ ] `hs log watch` — tail en tiempo real durante el juego\n- [ ] Integración Battle.net OAuth como flag opcional `--verify` para validación oficial de mazos\n\nPhase 2 será exclusivo de PC/Mac (Power.log no existe en móvil/consola).\n\n## Lo que no puede hacer\n\nLimitaciones de Phase 1 — no son bugs:\n\n- ❌ **Mis mazos guardados** — la API de Blizzard no tiene endpoints de perfil de Hearthstone (WoW/D3 sí; Hearthstone nunca recibió uno)\n- ❌ **Historial de partidas / ratio de victorias / colección** — misma razón\n- ❌ **Esbirros de taberna de Battlegrounds** — cobertura parcial en ambas fuentes\n- ❌ **Cartas eliminadas anteriores a Bosque Embrujado** — algunos `dbfId` muy antiguos aparecen como `Unknown (id)` tanto en HearthstoneJSON como en la API oficial\n\nSi tu mazo decodificado está lleno de `Unknown (id)` para un mazo que funcionaba ayer, o el código está corrupto o es de una cuenta no sincronizada.\n\n## Contribuir\n\nProyecto personal en etapa temprana pero PRs bienvenidas. Abre un issue primero para cambios no triviales.\n\nEl estilo está forzado por oxlint — `bun run check` debe pasar.\n\n## Licencia\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsay8425%2Fhs-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsay8425%2Fhs-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsay8425%2Fhs-cli/lists"}