@hablala/cli 0.12.11 → 0.13.1
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 +58 -28
- package/dist/index.js +314 -1096
- package/dist/index.js.map +1 -1
- package/package.json +5 -4
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 **
|
|
5
|
-
|
|
6
|
-
(reconciliación transaccional). Pensado para que un
|
|
7
|
-
equivalente) deje un negocio operando en minutos escribiendo
|
|
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 (
|
|
18
|
-
# … el agente edita
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
36
|
-
├──
|
|
37
|
-
|
|
38
|
-
├──
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
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
|
-
- **
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
-
|
|
53
|
-
|
|
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/
|
|
78
|
-
auth +
|
|
79
|
-
idempotencia viven en el servidor.
|
|
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.
|