cli_plazavea1



██████  ██       █████  ███████  █████      ██    ██ ███████  █████
██   ██ ██      ██   ██    ███  ██   ██     ██    ██ ██      ██   ██
██████  ██      ███████   ███   ███████     ██    ██ █████   ███████
██      ██      ██   ██  ███    ██   ██      ██  ██  ██      ██   ██
██      ███████ ██   ██ ███████ ██   ██       ████   ███████ ██   ██

Por qué existe

La app de Plaza Vea muestra tus órdenes pero no las suma, no las analiza, y no hay forma de que un agente AI opere tus compras. Este CLI crea ese canal.

AHA moment: Le pides a tu agente "agrega leche Gloria para mi casa en Lince".
Busca, simula el stock en tu local, y descubre que en Lince no hay — aunque la web
la muestre "disponible". Te avisa antes de agregarla, en vez de que el checkout
falle al final. Ni la app ni la web hacen eso.

# Lo mismo desde tu terminal (o vía MCP), sin abrir el browser:
plazavea simulate --list-addresses             # tus direcciones (0 = Lince, 1 = Cercado)
plazavea search "leche gloria"                 # catálogo + precios reales
plazavea simulate --sku 11389962 --address 0   # ✖ sin stock en Lince (la web diría "disponible")
plazavea simulate --sku 11389962 --address 1   # ✔ sí hay en Cercado
# Agregas solo lo que tu local sí tiene → el checkout no falla.

Qué hace

• 🤖 MCP server — Claude Code, Cursor o cualquier cliente MCP opera tus compras nativamente (14 tools)
• 📍 Verificar stock local (simulate_stock) — distingue stock global de stock en tu tienda
• 🔍 Buscar con los 3 niveles de precio (regular, descuento sin tarjeta, Tarjeta OH)
• 🛒 Gestionar carrito desde terminal (lo que Claude agrega se ve en la app y viceversa)
• 📦 Historial de pedidos que la app no analiza
• 🔒 Pago exclusivamente humano — el CLI llega hasta el carrito; el checkout lo abrís vos en el browser

Flujo (máquina de 4 estados)

VTEX no es un CRUD simple: es una máquina de estados. El flujo está dividido en 4 estados
estrictos para evitar errores cíclicos (CHK0041, pérdida de calle):

Stock local solo en simulate_stock, no en search. El search de plazavea es global
por diseño (catálogo cacheado en CDN, no regionalizable por usuario). simulate_stock es
el único punto donde VTEX expone disponibilidad por región, vía el orderForm.

Browser handoff (login y checkout)

open_login y open_checkout te ofrecen dos opciones (el agente pregunta cuál prefieres):
(A) abre el navegador automáticamente en tu máquina, o (B) te da el comando para que
lo ejecutes en tu propia terminal. Ambas respetan el guardrail: el browser abre y tú pagas
— el servidor nunca ejecuta el pago.

Limitaciones conocidas

• 🔒 Pago humano — el CLI llega hasta el carrito; el checkout y el pago los haces tú en el browser. No automatizable por diseño (guardrail de seguridad).
• ⚖️ Productos de pesaje — frutas, verduras y carnes vendidas por kg no se pueden agregar todavía (requieren un flujo de cantidad-por-peso que el modelo aún no maneja). En el roadmap.
• 📄 Búsqueda sin paginación — search devuelve hasta --limit 50 resultados; no hay scroll de páginas (suficiente para uso con agentes).
• 🏪 Solo Plaza Vea — la arquitectura VTEX es portable a Wong, Tottus y Vivanda, pero aún no están implementados.

Instalar

git clone https://github.com/StephCastrof001/cli_plazavea1.git
cd cli_plazavea1
bun install

Requiere Bun y Node.js.

Login

bun run index.ts login       # Abre browser — inicia sesión con tu cuenta Plaza Vea

El comando abre Chrome en el login de Plaza Vea. Inicias sesión manualmente y el CLI
captura la cookie de sesión automáticamente (tu contraseña nunca se guarda).

Login manual (fallback)

Si el browser no abre, copia el header Cookie: completo desde el Network tab de DevTools:

bun run index.ts login --manual "VtexIdclientAutCookie_plazavea=...; vtex_session=..."

Uso CLI

# Búsqueda
bun run index.ts search "leche gloria" --limit 10
bun run index.ts search "arroz" --output json

# Carrito
bun run index.ts cart                          # Ver carrito
bun run index.ts add <skuId> --quantity 2      # Agregar (--dry-run para preview)
bun run index.ts remove <índice>               # Eliminar ítem

# Stock por local (evita bug global vs local)
bun run index.ts simulate --sku <skuId>              # usa 1era dirección guardada
bun run index.ts simulate --sku <skuId> --address 1  # usa 2da dirección
bun run index.ts simulate --list-addresses           # ver todas las direcciones

# Pedidos
bun run index.ts orders --limit 5

# Sesión
bun run index.ts whoami                         # Estado de sesión + antigüedad
bun run index.ts logout                         # Cerrar sesión

REST API

bun run server.ts    # Inicia en http://localhost:3847

Servidor MCP (integración con Claude Code, Cursor, etc.)

El CLI incluye un servidor MCP que expone tools para que cualquier cliente MCP opere Plaza Vea nativamente.

Setup para Claude Code

Agrega .mcp.json a la raíz de tu proyecto:

{
  "mcpServers": {
    "plaza-vea": {
      "command": "/ruta/completa/a/bun",
      "args": ["run", "/path/to/plazavea-cli/src/mcp/index.ts"]
    }
  }
}

Nota: usa la ruta completa a bun (no solo "bun"). En macOS/Linux: which bun. En Windows: C:/Users/<usuario>/.bun/bin/bun.exe.

Setup para Claude Desktop

Edita el archivo de configuración de Claude Desktop:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "Plaza Vea 🛒": {
      "command": "C:/Users/TU_USUARIO/.bun/bin/bun.exe",
      "args": ["run", "C:/ruta/completa/a/plazavea-cli/src/mcp/index.ts"]
    }
  }
}

Claude Desktop no hereda el PATH del shell — la ruta completa a bun es obligatoria.
Reinicia Claude Desktop después de guardar el archivo.

Setup para Cursor

Agrega en Settings → MCP Servers:

{
  "Plaza Vea 🛒": {
    "command": "/ruta/completa/a/bun",
    "args": ["run", "/ruta/completa/a/plazavea-cli/src/mcp/index.ts"]
  }
}

Tools disponibles (14)

Estructura de precios (3 niveles)

Plaza Vea tiene hasta 3 precios por producto — no siempre aparecen los 3:

VTEX codifica el precio OH en dos lugares según la campaña (Teasers o Installments).
El CLI busca en ambos. Ver RESEARCH.md para el detalle.

Arquitectura

index.ts             → Dispatcher (login→Node+tsx, resto→Bun)
server.ts            → REST API (Hono, puerto 3847)
src/
  constants.ts       → BASE_URL (tienda) + WWW_BASE_URL (www) + endpoints
  http.ts            → Cliente HTTP tipado + AppError (isSessionExpired)
  config.ts          → Config con Zod en ~/.config/plazavea/session.json
  schemas/           → Zod: product (PriceInfo 3 niveles), cart
  services/          → Lógica por estado (máquina de 4 estados VTEX):
                        shipping.ts    → núcleo aislado del envío (Híbrido Inteligente)
                        address.ts     → Estado 1 (anclaje de dirección)
                        cart.ts        → Estado 2 (solo items)
                        fulfillment.ts → Estado 3 (simulate + gate de checkout)
                        auth (Playwright), products, orders, analytics, tracker
  commands/          → Un archivo por comando
  scripts/handoff.ts → Checkout en browser (Node+tsx, ADR-0001)
  mcp/index.ts       → Servidor MCP (14 tools)

Doble host (importante)

• tienda.plazavea.com.pe → search / catálogo
• www.plazavea.com.pe → carrito, orderForm, simulate, OMS / orders

La misma cookie funciona en ambos (dominio .plazavea.com.pe).

Type Safety

Toda respuesta de VTEX se valida con Zod antes de usarse:

• Búsqueda → schemas/product.ts (normaliza el JSON caótico de VTEX a PriceInfo)
• Carrito → schemas/cart.ts (centavos → soles)
• Errores → AppError con detección de sesión expirada (401/403)

Consideraciones de seguridad

Herramienta de uso local y personal. Corre enteramente en tu máquina — no envía datos
a terceros (excepto las APIs de Plaza Vea). Trabajar con tu sesión real conlleva riesgos.

• La cookie de sesión se guarda en texto plano en ~/.config/plazavea/session.json
  (con chmod 600 en sistemas Unix). Cualquiera con acceso a tu home podría leerla.
• Ejecuta logout cuando termines para limpiar la sesión.
• El servidor REST (server.ts) abre en localhost sin autenticación — no lo expongas a la red.
• Usando MCP, los datos de tus pedidos/carrito se envían como texto al modelo de Claude.
• Proyecto no oficial, sin relación con Plaza Vea. Úsalo bajo tu propio riesgo.

Stack

• Bun — Runtime
• TypeScript — Strict, sin any
• Zod — Validación de schemas
• Hono — REST API
• Playwright — Login por browser
• MCP SDK — Integración con Claude (14 tools)