@hablala/cli

CLI de Workspace as Code de Hablalá: configura un workspace completo de la plataforma (modelo de datos, workflows, agentes) desde archivos declarativos versionables, con el ciclo estándar de la infraestructura declarativa: plan (diff, sin tocar nada) → apply (reconciliación transaccional). Pensado para que un agente de código (Claude Code o equivalente) deje un negocio operando en minutos escribiendo archivos — su medio nativo.

npx @hablala/cli --help

Ciclo

hablala login          # inicia sesión por el navegador (OAuth) y guarda la credencial
hablala init           # scaffold (CLAUDE.md, hablala.yaml) + pull del estado actual
# … el agente edita objects/, workflows/, agents/ …
hablala plan           # diff declarado vs. real (dry-run; detección de drift)
hablala apply          # reconcilia contra el workspace (crear/actualizar/archivar)
hablala pull           # re-sincroniza los archivos con lo cambiado por otras vías

hablala codegen        # tipos TS por tenant para @hablala/client (storefront token)

Es el CLI de la plataforma (un solo bin de marca con subcomandos, como prisma o supabase): los comandos de Workspace as Code usan un access token hpat_…; codegen usa un storefront token sfpk_…/sfpr_… (HABLALA_STOREFRONT_TOKEN) porque introspecciona el recorte publicado que el SDK lee.

El manifiesto

mi-negocio/
├── hablala.yaml              # metadatos del workspace (informativo)
├── objects/
│   └── vestido.yaml          # un objeto por archivo; sus relationships van dentro
├── workflows/
│   └── al_devolver.yaml
├── agents/
│   └── recepcionista.yaml
└── CLAUDE.md                 # generado por `init`: vocabulario + árbol de decisión

Reglas:

• Cada directorio presente es autoritativo: lo que existe en el workspace y no está declarado se archiva al aplicar (nunca se borra; plan siempre lo muestra antes). Un directorio ausente no se gestiona.
• El slug/handle del contenido es la identidad; el nombre de archivo es convención.
• Mismo manifiesto aplicado dos veces = no-op (idempotencia estructural).
• Validación local en milisegundos (claves conocidas, enums, identificadores) antes de tocar la red; la validación profunda la hace el servidor en el mismo plan.

Autenticación

hablala login usa los dos flujos OAuth estándar para CLIs nativos:

• Por defecto — navegador (Authorization Code + PKCE con loopback, RFC 8252): el CLI abre la web, apruebas eligiendo organización/workspace/permisos, y la credencial vuelve sola por 127.0.0.1. Nada que copiar.
• --device — sin navegador local (Device Authorization Grant, RFC 8628; se autodetecta bajo SSH): el CLI muestra un código corto (BDWP-HQPK) y la URL de verificación, y espera tu aprobación.

Ambos emiten el mismo access token de máquina (hpat_…) que se puede crear/revocar a mano en Configuración → Conexiones. La credencial es la identidad completa: organización y workspace se infieren del token. En CI, sáltate el navegador con --token hpat_….

Precedencia: --token > HABLALA_ACCESS_TOKEN > ~/.config/hablala/credentials.json (escrito por hablala login, modo 0600). Endpoint: --endpoint > HABLALA_ENDPOINT > default. Los endpoints OAuth se descubren por RFC 8414 (/.well-known/oauth-authorization-server).

Diseño

Capa fina sobre el endpoint declarativo del backend (GET/PUT /v1/workspace-config): auth + leer archivos + validación local + una llamada. El diff, la reconciliación y la idempotencia viven en el servidor. Ver apps/api/WORKSPACE_AS_CODE.md en el monorepo.