@hablala/cli 0.12.11 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,10 +1,11 @@
1
1
  # @hablala/cli
2
2
 
3
3
  CLI de **Account as Code** de Hablalá: configura la cuenta completa de la plataforma
4
- (modelo de datos, workflows, agentes) desde **archivos declarativos versionables**, con el ciclo
5
- estándar de la infraestructura declarativa: `plan` (diff, sin tocar nada) → `apply`
6
- (reconciliación transaccional). Pensado para que un agente de código (Claude Code o
7
- equivalente) deje un negocio operando en minutos escribiendo archivos — su medio nativo.
4
+ (modelo de datos, workflows, agentes) desde **un `hablala.config.ts` versionable** autorado
5
+ con el SDK `@hablala/schema/synth`, con el ciclo estándar de la infraestructura declarativa:
6
+ `plan` (diff, sin tocar nada) → `apply` (reconciliación transaccional). Pensado para que un
7
+ agente de código (Claude Code o equivalente) deje un negocio operando en minutos escribiendo
8
+ código tipado — su medio nativo.
8
9
 
9
10
  ```
10
11
  npx @hablala/cli --help
@@ -14,43 +15,70 @@ npx @hablala/cli --help
14
15
 
15
16
  ```
16
17
  hablala login # inicia sesión por el navegador (OAuth) y guarda la credencial
17
- hablala init # scaffold (CLAUDE.md, hablala.yaml) + pull del estado actual
18
- # … el agente edita objects/, workflows/, agents/ …
18
+ hablala init # scaffold (hablala.config.ts, package.json, tsconfig.json, CLAUDE.md) + pull del estado actual
19
+ # … el agente edita hablala.config.ts (puede importar módulos .ts propios) …
19
20
  hablala plan # diff declarado vs. real (dry-run; detección de drift)
20
21
  hablala apply # reconcilia contra el workspace (crear/actualizar/archivar)
21
- hablala pull # re-sincroniza los archivos con lo cambiado por otras vías
22
+ hablala pull # re-sincroniza el config con lo cambiado por otras vías
22
23
 
23
24
  hablala codegen # tipos TS por tenant para @hablala/client (API key)
24
25
  ```
25
26
 
26
- Es **el** CLI de la plataforma (un solo bin de marca con subcomandos, como `prisma` o
27
- `supabase`): los comandos de Account as Code usan un machine access token `mat_…`; `codegen`
27
+ Es **el** CLI de la plataforma (un solo bin de marca con subcomandos): los comandos de Account as Code usan un machine access token `mat_…`; `codegen`
28
28
  usa una API key `pk_…`/`sk_…` (`HABLALA_TOKEN`) porque
29
29
  introspecciona el recorte publicado que el SDK lee.
30
30
 
31
- ## El manifiesto
31
+ ## El `hablala.config.ts`
32
+
33
+ El tenant autora **un solo `hablala.config.ts`** con el SDK `@hablala/schema/synth`: *config as
34
+ actual code* (modelo de infraestructura-como-código aplicado al dominio). `init` siembra el proyecto:
32
35
 
33
36
  ```
34
37
  mi-negocio/
35
- ├── hablala.yaml # metadatos del workspace (informativo)
36
- ├── objects/
37
- │ └── producto.yaml # un objeto por archivo; sus relationships van dentro
38
- ├── workflows/
39
- │ └── al_devolver.yaml
40
- ├── agents/
41
- │ └── recepcionista.yaml
42
- └── CLAUDE.md # generado por `init`: vocabulario + árbol de decisión
38
+ ├── hablala.config.ts # el diccionario completo: objects, relationships, policies, workflows, agents
39
+ ├── package.json # devDependency @hablala/schema
40
+ ├── tsconfig.json
41
+ ├── .gitignore
42
+ ├── CLAUDE.md / AGENTS.md # generados por `init`: vocabulario + árbol de decisión
43
+ ```
44
+
45
+ Tras `hablala init` → `npm install`, se edita `hablala.config.ts` y se corre `hablala plan`. El
46
+ diccionario se declara con *constructs* tipados:
47
+
48
+ ```ts
49
+ import { Account, text, number, select, reference } from "@hablala/schema/synth";
50
+
51
+ const account = new Account({ kind: "organization" });
52
+
53
+ account.object("producto", {
54
+ title: "Productos",
55
+ titleSingular: "Producto",
56
+ description: "Producto del catálogo, unidad serializada.",
57
+ synonyms: ["product", "item"],
58
+ })
59
+ .attribute("categoria", select({ description: "Categoría.", isRequired: true, options: ["A", "B", "C"] }))
60
+ .attribute("sku", text({ title: "SKU", description: "Código único.", isUnique: true }))
61
+ // relationship hacia un módulo core, vía resource_record_id opaco
62
+ .relationship("producto_reservas", { target: "booking", cardinality: "one_to_many" });
63
+
64
+ export default account;
43
65
  ```
44
66
 
45
67
  Reglas:
46
68
 
47
- - **Cada directorio presente es autoritativo**: lo que existe en el workspace y no está
48
- declarado se **archiva** al aplicar (nunca se borra; `plan` siempre lo muestra antes).
49
- Un directorio ausente no se gestiona.
50
- - El `slug`/`handle` del contenido es la identidad; el nombre de archivo es convención.
51
- - Mismo manifiesto aplicado dos veces = no-op (idempotencia estructural).
52
- - Validación local en milisegundos (claves conocidas, enums, identificadores) antes de
53
- tocar la red; la validación profunda la hace el servidor en el mismo `plan`.
69
+ - **Un solo archivo de entrada** (`hablala.config.ts`); el tenant puede partirlo en varios
70
+ módulos `.ts` que él mismo importa.
71
+ - **Cada sección presente es autoritativa**: lo que existe en el workspace y no está declarado se
72
+ **archiva** al aplicar (nunca se borra; `plan` siempre lo muestra antes). Una sección ausente no
73
+ se gestiona. El modo por sección se ajusta con `account.mode("objects", "additive")`.
74
+ - El `slug`/`handle` declarado en cada construct es la identidad; el nombre de variable TS es
75
+ convención.
76
+ - Mismo config aplicado dos veces = no-op (idempotencia estructural).
77
+ - El CLI **transpila** `hablala.config.ts` con esbuild y corre `account.synth()` para producir el
78
+ manifiesto JSON que `PUT /v1/account-config` acepta (igual que un `synth` de infraestructura-como-código emite su plantilla de despliegue): el
79
+ contrato wire con el backend no cambia.
80
+ - Validación local con tipos de TypeScript al editar y con Zod (`@hablala/schema`) al sintetizar,
81
+ antes de tocar la red; la validación profunda la hace el servidor en el mismo `plan`.
54
82
 
55
83
  ## Autenticación
56
84
 
@@ -74,6 +102,8 @@ default. Los endpoints OAuth se descubren por RFC 8414
74
102
 
75
103
  ## Diseño
76
104
 
77
- Capa fina sobre el endpoint declarativo del backend (`GET/PUT /v1/workspace-config`):
78
- auth + leer archivos + validación local + una llamada. El diff, la reconciliación y la
79
- idempotencia viven en el servidor. Ver `apps/api/ACCOUNT_AS_CODE.md` en el monorepo.
105
+ Capa fina sobre el endpoint declarativo del backend (`GET/PUT /v1/account-config`):
106
+ auth + transpilar y sintetizar el `hablala.config.ts` + validación local + una llamada. El
107
+ diff, la reconciliación y la idempotencia viven en el servidor. La forma del diccionario la
108
+ define el paquete Zod `@hablala/schema` (ver `docs/adr/0003-data-dictionary-authoring-ts-sdk.md`).
109
+ Ver `apps/api/ACCOUNT_AS_CODE.md` en el monorepo.