@roilab/crm-cli 0.24.0 → 0.25.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/CHANGELOG.md +40 -0
- package/README.md +197 -197
- package/SKILL.md +16 -2
- package/SURFACE.txt +526 -512
- package/dist/bin/crm.js +2 -0
- package/dist/bin/crm.js.map +1 -1
- package/dist/src/commands/guide.js +57 -0
- package/dist/src/commands/guide.js.map +1 -0
- package/dist/src/commands/site.js +37 -1
- package/dist/src/commands/site.js.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,46 @@ Todos los cambios notables se documentan aquí. El formato sigue
|
|
|
6
6
|
|
|
7
7
|
## [Sin publicar]
|
|
8
8
|
|
|
9
|
+
## [0.25.0] — 2026-11-17
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- **`crm guide list` y `crm guide get <slug>`.** Leen las guías de la
|
|
14
|
+
biblioteca de Guías (internas de Roilab y de clientes) con el mismo filtro
|
|
15
|
+
que el web: un member ve las internas, las de todos los clientes y las de
|
|
16
|
+
sus clientes. `get` devuelve el texto en markdown en `data.body` (la versión
|
|
17
|
+
publicada, o el borrador con `--draft`) y avisa con `hasUnpublishedChanges`
|
|
18
|
+
si el borrador difiere. Leer por aquí no marca la guía como leída. Scope
|
|
19
|
+
nuevo `guides:read`, solo staff.
|
|
20
|
+
- **`crm site stock`.** Stock real de la tienda, leído en el momento del
|
|
21
|
+
webservice (solo lectura): de una ficha, unidades totales y por combinación
|
|
22
|
+
y qué pasa al agotarse; de una categoría, sus fichas activas con su stock,
|
|
23
|
+
primero las agotadas (las que más venden arriba) y con ventas de 90 días, y
|
|
24
|
+
sus combinaciones: cuántas tiene cada ficha y cuántas están agotadas, con el
|
|
25
|
+
total de la categoría y las fichas con stock que tienen algún pack a cero.
|
|
26
|
+
`--agotados`, `--combinaciones-agotadas` (fichas con alguna combinación
|
|
27
|
+
agotada), `--combinaciones` (nombre y unidades de cada combinación) e
|
|
28
|
+
`--inactivos`. Solo en tiendas con el stock activado en su
|
|
29
|
+
conexión (growbaratochile.cl); en growbarato.net no es real. `crm site get`
|
|
30
|
+
de una ficha trae el total en `stock`.
|
|
31
|
+
|
|
32
|
+
### Changed
|
|
33
|
+
|
|
34
|
+
- **Tiendas con URLs sin id** (growbaratochile.cl: `/fertilizantes/`,
|
|
35
|
+
`/boom-nutrients/candy-tripack.html`). `crm site get`, `update`, `sales` y
|
|
36
|
+
`stock` reconocen la ficha, categoría o CMS abriendo la página publicada; los
|
|
37
|
+
números del slug ya no se leen como id (`60-day-wonder.html` no es la ficha
|
|
38
|
+
60). Si la URL redirige, se usa la página final y sale en `warnings`. En las
|
|
39
|
+
tiendas con id en la URL, una ruta que no se reconoce también se resuelve
|
|
40
|
+
así en vez de fallar.
|
|
41
|
+
- `crm site sales` da las cifras en la moneda de la tienda (`currency`).
|
|
42
|
+
|
|
43
|
+
### Fixed
|
|
44
|
+
|
|
45
|
+
- `crm site get` y `update` en tiendas PrestaShop con un solo idioma
|
|
46
|
+
(growbaratochile.cl) fallaban con "Server Error": su webservice devuelve los
|
|
47
|
+
textos como texto y no por idioma. Arreglado en el servidor.
|
|
48
|
+
|
|
9
49
|
## [0.24.0] — 2026-11-13
|
|
10
50
|
|
|
11
51
|
### Fixed
|
package/README.md
CHANGED
|
@@ -1,197 +1,197 @@
|
|
|
1
|
-
# @roilab/crm-cli
|
|
2
|
-
|
|
3
|
-
> CLI for humans and AI agents to drive the ROILab SEO+CRM platform.
|
|
4
|
-
|
|
5
|
-
CLI para el SEO + CRM de ROILab, pensado tanto para humanos como para agentes de
|
|
6
|
-
IA (Claude Code, Cursor, Windsurf). Envoltura JSON siempre, exit codes numéricos,
|
|
7
|
-
escrituras idempotentes y login sin pegar API keys en texto plano (flujo de
|
|
8
|
-
dispositivo tipo OAuth).
|
|
9
|
-
|
|
10
|
-
## Instalación
|
|
11
|
-
|
|
12
|
-
### Agentes (recomendado)
|
|
13
|
-
|
|
14
|
-
Sin instalación previa, siempre la última versión:
|
|
15
|
-
|
|
16
|
-
```bash
|
|
17
|
-
npx -y @roilab/crm-cli@latest <comando>
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
### Humanos
|
|
21
|
-
|
|
22
|
-
Para dejar `crm` en el PATH:
|
|
23
|
-
|
|
24
|
-
```bash
|
|
25
|
-
npm i -g @roilab/crm-cli
|
|
26
|
-
crm --help
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
Actualiza con:
|
|
30
|
-
|
|
31
|
-
```bash
|
|
32
|
-
crm update # = npm i -g @roilab/crm-cli@latest; --check solo compara
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
No hace falta acordarse: el propio CLI comprueba una vez al día si hay una
|
|
36
|
-
versión nueva en npm y el servidor lo recuerda en cada respuesta, siempre por
|
|
37
|
-
stderr. Cambiar webs (`crm site update`) exige una versión mínima: por debajo,
|
|
38
|
-
el servidor pide `crm update`.
|
|
39
|
-
|
|
40
|
-
## Primer login (30 segundos)
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
crm auth login --device-name mi-portatil
|
|
44
|
-
# Abre la URL que aparece en el navegador, aprueba.
|
|
45
|
-
crm auth whoami
|
|
46
|
-
crm doctor
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
El CLI guarda tokens rotativos en `~/.config/crm/credentials.json` (modo `0600`).
|
|
50
|
-
Nunca se escribe una API key en claro en disco por esta vía.
|
|
51
|
-
|
|
52
|
-
## Comandos
|
|
53
|
-
|
|
54
|
-
```bash
|
|
55
|
-
crm recall https://example.com/pricing
|
|
56
|
-
crm task list --status todo --domain dom_xyz --limit 20
|
|
57
|
-
crm task create --title "Arreglar H1 en /pricing" --domain dom_xyz --shadow
|
|
58
|
-
crm task update tsk_abc --status done --completed-at 2026-10-28
|
|
59
|
-
crm review approve task tsk_abc # aprueba una propuesta o quita la marca REVISAR
|
|
60
|
-
crm comment create --task tsk_abc --body "Desplegado en prod" --kind agent_log
|
|
61
|
-
crm domain metrics dom_xyz --start 2026-03-01 --end 2026-04-01 --markdown
|
|
62
|
-
crm review list --mine
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
`crm --help` imprime todos los sustantivos; `crm <noun> --help` imprime los
|
|
66
|
-
verbos; la documentación completa vive en la app, pestaña **Documentación**, que
|
|
67
|
-
se auto-genera desde el registro de endpoints — siempre refleja la versión
|
|
68
|
-
servida.
|
|
69
|
-
|
|
70
|
-
## Cambiar la tienda y el blog (`crm site`)
|
|
71
|
-
|
|
72
|
-
Con las credenciales guardadas en el CRM (ficha del dominio → Conexiones con la
|
|
73
|
-
web) se leen y cambian el H1, el meta title, la meta description, el contenido,
|
|
74
|
-
el noindex y el canonical de la tienda PrestaShop y del blog WordPress. La
|
|
75
|
-
credencial no sale del servidor y cada cambio queda en el registro de cambios de
|
|
76
|
-
su tarea.
|
|
77
|
-
|
|
78
|
-
```bash
|
|
79
|
-
crm site list # webs que puedes usar
|
|
80
|
-
crm site rules --url https://www.tienda.com/ # reglas de publicación (obligatorio antes de escribir)
|
|
81
|
-
crm site get --url https://www.tienda.com/598-cbd # valores actuales
|
|
82
|
-
crm site update --task tsk_abc --url https://www.tienda.com/598-cbd \
|
|
83
|
-
--meta-title-file title.txt --meta-desc-file desc.txt --dry-run
|
|
84
|
-
crm site update --task tsk_abc --url https://www.tienda.com/598-cbd \
|
|
85
|
-
--meta-title-file title.txt --meta-desc-file desc.txt --note "por qué"
|
|
86
|
-
|
|
87
|
-
# Indexación: noindex exige --allow-noindex y enseña los clics de la URL en Search Console
|
|
88
|
-
crm site update --task tsk_abc --url https://www.tienda.com/520-vacia --noindex noindex --allow-noindex --dry-run
|
|
89
|
-
crm site update --task tsk_abc --url https://www.tienda.com/77-dup.html --canonical https://www.tienda.com/76-buena.html --dry-run
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
Noindex y canonical: en WordPress hace falta el mu-plugin `roilab-seo-rest` 1.1
|
|
93
|
-
(Rank Math o Yoast); en PrestaShop, el módulo SEO de Roilab (rlseourls) con sus
|
|
94
|
-
recursos del webservice. Poner una página en noindex exige `--allow-noindex` y
|
|
95
|
-
la respuesta trae `searchConsole` con sus clics e impresiones de 90 días. El
|
|
96
|
-
canonical tiene que ser del mismo dominio y apuntar a una página que responda
|
|
97
|
-
200 y se pueda indexar; si no, se bloquea.
|
|
98
|
-
|
|
99
|
-
### Ventas de la tienda (`crm site sales`)
|
|
100
|
-
|
|
101
|
-
Para decidir con dinero real, no con
|
|
102
|
-
cada noche las ventas de las tiendas PrestaShop conectadas (pedidos válidos y
|
|
103
|
-
no cancelados de la tienda e idioma de la conexión, sin IVA; nada de datos de
|
|
104
|
-
clientes). La clave del webservice necesita permiso de lectura (GET) en
|
|
105
|
-
`orders` y `order_details`.
|
|
106
|
-
|
|
107
|
-
```bash
|
|
108
|
-
crm site sales --url https://www.tienda.com/598-cbd # categoría: 28 y 90 días, interanual, top 10 fichas
|
|
109
|
-
crm site sales --ref product:5090 --connection <id> # ficha: y su puesto en la categoría
|
|
110
|
-
crm site sales --top 50 --connection <id> # ranking de fichas por facturación de 90 días
|
|
111
|
-
crm site sales --top 20 --category 598 --days 28 --connection <id>
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
Una categoría suma todas las fichas asociadas a ella o a sus subcategorías,
|
|
115
|
-
como las lista la tienda, no solo las que la tienen por defecto. El interanual compara con las mismas fechas de hace 52 semanas.
|
|
116
|
-
La revisión de métricas de una tarea añade las ventas de sus fichas y
|
|
117
|
-
categorías antes y después.
|
|
118
|
-
|
|
119
|
-
Para comportamiento (sesiones, interacción, tiempo en página) está
|
|
120
|
-
`crm ga4 query --dimensions pagePath`; para dinero, siempre la tienda.
|
|
121
|
-
|
|
122
|
-
Norma de trabajo: ningún cambio se aplica sin el OK explícito de la persona que
|
|
123
|
-
hace la tarea. El agente enseña el `--dry-run`, espera un "sí, publica", aplica y
|
|
124
|
-
deja la decisión en un comentario de la tarea (`--kind decision`).
|
|
125
|
-
|
|
126
|
-
`update` escribe solo lo que cambia, vuelve a leer la página para confirmar lo
|
|
127
|
-
guardado, comprueba la página publicada y registra el cambio con el antes y el
|
|
128
|
-
después reales. No escribe si no has leído en las últimas 24 horas la versión
|
|
129
|
-
vigente de las reglas de la web (perfil del dominio, normas, skills y documentos),
|
|
130
|
-
y bloquea lo que las incumple de forma medible.
|
|
131
|
-
|
|
132
|
-
## Seguimiento de URLs (`crm task tracking`)
|
|
133
|
-
|
|
134
|
-
Cada cambio registrado mete su URL en el seguimiento de la tarea; al
|
|
135
|
-
completarla, la revisión de métricas se programa sola (28 días por defecto) y
|
|
136
|
-
mide esas URLs en Search Console. Para medir un grupo o el dominio entero:
|
|
137
|
-
|
|
138
|
-
```bash
|
|
139
|
-
crm task tracking get tsk_abc
|
|
140
|
-
crm task tracking set tsk_abc --pattern '\.html$' # todas las fichas
|
|
141
|
-
crm task tracking set tsk_abc --domain
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
## Adjuntar archivos (`--file`)
|
|
145
|
-
|
|
146
|
-
`task create` / `task update` / `comment create` / `chat send` / `chat reply`
|
|
147
|
-
aceptan `--file <ruta>` (repetible). Es **un flag, no un subcomando** — no
|
|
148
|
-
existe `crm task attach` ni `crm upload`. El CLI sube cada archivo a Convex
|
|
149
|
-
storage en dos pasos y manda los `attachments[]` en la misma escritura.
|
|
150
|
-
|
|
151
|
-
```bash
|
|
152
|
-
crm task create --title "Migración H1" --domain dom_xyz \
|
|
153
|
-
--file ./brief.pdf --file ./screenshot.png
|
|
154
|
-
|
|
155
|
-
crm comment create --task tsk_abc --kind decision \
|
|
156
|
-
--body "Cerrado, ver diff" --file ./after.png
|
|
157
|
-
|
|
158
|
-
crm chat send "$TID" --body "captura del 404" --file ./bug.png
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
Reglas:
|
|
162
|
-
|
|
163
|
-
- Máx **10 MB por archivo** (rechazo local antes de tocar la red).
|
|
164
|
-
- Aviso en stderr desde **2 MB** (`[AVISO] ... la subida puede tardar.`).
|
|
165
|
-
- En `task update` la lista de adjuntos es **REEMPLAZO**, no merge. Usa
|
|
166
|
-
`--clear-files` para vaciar; pasa los antiguos junto con los nuevos si
|
|
167
|
-
quieres conservarlos.
|
|
168
|
-
- `--body` se vuelve opcional cuando hay `--file`.
|
|
169
|
-
|
|
170
|
-
## Flags globales
|
|
171
|
-
|
|
172
|
-
Disponibles en cada comando:
|
|
173
|
-
|
|
174
|
-
- `--json` — envoltura JSON completa (por defecto).
|
|
175
|
-
- `--quiet` — solo `data`.
|
|
176
|
-
- `--ids-only` — un id por línea.
|
|
177
|
-
- `--count` — un único entero.
|
|
178
|
-
- `--markdown` — resumen legible (no es JSON).
|
|
179
|
-
- `--jq <expr>` — jq mini (`.a`, `.a.b`, `.a[]`, `.a[].b`).
|
|
180
|
-
- `--shadow` — fuerza que la escritura aterrice como propuesta pendiente de
|
|
181
|
-
revisión humana.
|
|
182
|
-
- `--wait-for-approval --timeout 30m` — bloquea hasta que un humano decida.
|
|
183
|
-
- `--idempotency-key <key>` — idempotency key estable (automática en escrituras).
|
|
184
|
-
|
|
185
|
-
## Seguridad
|
|
186
|
-
|
|
187
|
-
- Sin scripts `preinstall` / `postinstall` / `install` — nada que se ejecute al
|
|
188
|
-
instalar el paquete.
|
|
189
|
-
- Auth por flujo de dispositivo: no se comparten secretos entre máquinas; el
|
|
190
|
-
access token caduca en 1 h y el refresh token rota en cada uso.
|
|
191
|
-
- Archivo de credenciales con permisos `0600`, aislado por perfil.
|
|
192
|
-
- Publicación con atestación de procedencia (`npm publish --provenance`) para
|
|
193
|
-
que se pueda verificar el origen del tarball.
|
|
194
|
-
|
|
195
|
-
## Licencia
|
|
196
|
-
|
|
197
|
-
MIT — ver [LICENSE](./LICENSE).
|
|
1
|
+
# @roilab/crm-cli
|
|
2
|
+
|
|
3
|
+
> CLI for humans and AI agents to drive the ROILab SEO+CRM platform.
|
|
4
|
+
|
|
5
|
+
CLI para el SEO + CRM de ROILab, pensado tanto para humanos como para agentes de
|
|
6
|
+
IA (Claude Code, Cursor, Windsurf). Envoltura JSON siempre, exit codes numéricos,
|
|
7
|
+
escrituras idempotentes y login sin pegar API keys en texto plano (flujo de
|
|
8
|
+
dispositivo tipo OAuth).
|
|
9
|
+
|
|
10
|
+
## Instalación
|
|
11
|
+
|
|
12
|
+
### Agentes (recomendado)
|
|
13
|
+
|
|
14
|
+
Sin instalación previa, siempre la última versión:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npx -y @roilab/crm-cli@latest <comando>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
### Humanos
|
|
21
|
+
|
|
22
|
+
Para dejar `crm` en el PATH:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm i -g @roilab/crm-cli
|
|
26
|
+
crm --help
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Actualiza con:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
crm update # = npm i -g @roilab/crm-cli@latest; --check solo compara
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
No hace falta acordarse: el propio CLI comprueba una vez al día si hay una
|
|
36
|
+
versión nueva en npm y el servidor lo recuerda en cada respuesta, siempre por
|
|
37
|
+
stderr. Cambiar webs (`crm site update`) exige una versión mínima: por debajo,
|
|
38
|
+
el servidor pide `crm update`.
|
|
39
|
+
|
|
40
|
+
## Primer login (30 segundos)
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
crm auth login --device-name mi-portatil
|
|
44
|
+
# Abre la URL que aparece en el navegador, aprueba.
|
|
45
|
+
crm auth whoami
|
|
46
|
+
crm doctor
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
El CLI guarda tokens rotativos en `~/.config/crm/credentials.json` (modo `0600`).
|
|
50
|
+
Nunca se escribe una API key en claro en disco por esta vía.
|
|
51
|
+
|
|
52
|
+
## Comandos
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
crm recall https://example.com/pricing
|
|
56
|
+
crm task list --status todo --domain dom_xyz --limit 20
|
|
57
|
+
crm task create --title "Arreglar H1 en /pricing" --domain dom_xyz --shadow
|
|
58
|
+
crm task update tsk_abc --status done --completed-at 2026-10-28
|
|
59
|
+
crm review approve task tsk_abc # aprueba una propuesta o quita la marca REVISAR
|
|
60
|
+
crm comment create --task tsk_abc --body "Desplegado en prod" --kind agent_log
|
|
61
|
+
crm domain metrics dom_xyz --start 2026-03-01 --end 2026-04-01 --markdown
|
|
62
|
+
crm review list --mine
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`crm --help` imprime todos los sustantivos; `crm <noun> --help` imprime los
|
|
66
|
+
verbos; la documentación completa vive en la app, pestaña **Documentación**, que
|
|
67
|
+
se auto-genera desde el registro de endpoints — siempre refleja la versión
|
|
68
|
+
servida.
|
|
69
|
+
|
|
70
|
+
## Cambiar la tienda y el blog (`crm site`)
|
|
71
|
+
|
|
72
|
+
Con las credenciales guardadas en el CRM (ficha del dominio → Conexiones con la
|
|
73
|
+
web) se leen y cambian el H1, el meta title, la meta description, el contenido,
|
|
74
|
+
el noindex y el canonical de la tienda PrestaShop y del blog WordPress. La
|
|
75
|
+
credencial no sale del servidor y cada cambio queda en el registro de cambios de
|
|
76
|
+
su tarea.
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
crm site list # webs que puedes usar
|
|
80
|
+
crm site rules --url https://www.tienda.com/ # reglas de publicación (obligatorio antes de escribir)
|
|
81
|
+
crm site get --url https://www.tienda.com/598-cbd # valores actuales
|
|
82
|
+
crm site update --task tsk_abc --url https://www.tienda.com/598-cbd \
|
|
83
|
+
--meta-title-file title.txt --meta-desc-file desc.txt --dry-run
|
|
84
|
+
crm site update --task tsk_abc --url https://www.tienda.com/598-cbd \
|
|
85
|
+
--meta-title-file title.txt --meta-desc-file desc.txt --note "por qué"
|
|
86
|
+
|
|
87
|
+
# Indexación: noindex exige --allow-noindex y enseña los clics de la URL en Search Console
|
|
88
|
+
crm site update --task tsk_abc --url https://www.tienda.com/520-vacia --noindex noindex --allow-noindex --dry-run
|
|
89
|
+
crm site update --task tsk_abc --url https://www.tienda.com/77-dup.html --canonical https://www.tienda.com/76-buena.html --dry-run
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Noindex y canonical: en WordPress hace falta el mu-plugin `roilab-seo-rest` 1.1
|
|
93
|
+
(Rank Math o Yoast); en PrestaShop, el módulo SEO de Roilab (rlseourls) con sus
|
|
94
|
+
recursos del webservice. Poner una página en noindex exige `--allow-noindex` y
|
|
95
|
+
la respuesta trae `searchConsole` con sus clics e impresiones de 90 días. El
|
|
96
|
+
canonical tiene que ser del mismo dominio y apuntar a una página que responda
|
|
97
|
+
200 y se pueda indexar; si no, se bloquea.
|
|
98
|
+
|
|
99
|
+
### Ventas de la tienda (`crm site sales`)
|
|
100
|
+
|
|
101
|
+
Para decidir con dinero real, no con Analytics. El CRM suma
|
|
102
|
+
cada noche las ventas de las tiendas PrestaShop conectadas (pedidos válidos y
|
|
103
|
+
no cancelados de la tienda e idioma de la conexión, sin IVA; nada de datos de
|
|
104
|
+
clientes). La clave del webservice necesita permiso de lectura (GET) en
|
|
105
|
+
`orders` y `order_details`.
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
crm site sales --url https://www.tienda.com/598-cbd # categoría: 28 y 90 días, interanual, top 10 fichas
|
|
109
|
+
crm site sales --ref product:5090 --connection <id> # ficha: y su puesto en la categoría
|
|
110
|
+
crm site sales --top 50 --connection <id> # ranking de fichas por facturación de 90 días
|
|
111
|
+
crm site sales --top 20 --category 598 --days 28 --connection <id>
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Una categoría suma todas las fichas asociadas a ella o a sus subcategorías,
|
|
115
|
+
como las lista la tienda, no solo las que la tienen por defecto. El interanual compara con las mismas fechas de hace 52 semanas.
|
|
116
|
+
La revisión de métricas de una tarea añade las ventas de sus fichas y
|
|
117
|
+
categorías antes y después.
|
|
118
|
+
|
|
119
|
+
Para comportamiento (sesiones, interacción, tiempo en página) está
|
|
120
|
+
`crm ga4 query --dimensions pagePath`; para dinero, siempre la tienda.
|
|
121
|
+
|
|
122
|
+
Norma de trabajo: ningún cambio se aplica sin el OK explícito de la persona que
|
|
123
|
+
hace la tarea. El agente enseña el `--dry-run`, espera un "sí, publica", aplica y
|
|
124
|
+
deja la decisión en un comentario de la tarea (`--kind decision`).
|
|
125
|
+
|
|
126
|
+
`update` escribe solo lo que cambia, vuelve a leer la página para confirmar lo
|
|
127
|
+
guardado, comprueba la página publicada y registra el cambio con el antes y el
|
|
128
|
+
después reales. No escribe si no has leído en las últimas 24 horas la versión
|
|
129
|
+
vigente de las reglas de la web (perfil del dominio, normas, skills y documentos),
|
|
130
|
+
y bloquea lo que las incumple de forma medible.
|
|
131
|
+
|
|
132
|
+
## Seguimiento de URLs (`crm task tracking`)
|
|
133
|
+
|
|
134
|
+
Cada cambio registrado mete su URL en el seguimiento de la tarea; al
|
|
135
|
+
completarla, la revisión de métricas se programa sola (28 días por defecto) y
|
|
136
|
+
mide esas URLs en Search Console. Para medir un grupo o el dominio entero:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
crm task tracking get tsk_abc
|
|
140
|
+
crm task tracking set tsk_abc --pattern '\.html$' # todas las fichas
|
|
141
|
+
crm task tracking set tsk_abc --domain
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## Adjuntar archivos (`--file`)
|
|
145
|
+
|
|
146
|
+
`task create` / `task update` / `comment create` / `chat send` / `chat reply`
|
|
147
|
+
aceptan `--file <ruta>` (repetible). Es **un flag, no un subcomando** — no
|
|
148
|
+
existe `crm task attach` ni `crm upload`. El CLI sube cada archivo a Convex
|
|
149
|
+
storage en dos pasos y manda los `attachments[]` en la misma escritura.
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
crm task create --title "Migración H1" --domain dom_xyz \
|
|
153
|
+
--file ./brief.pdf --file ./screenshot.png
|
|
154
|
+
|
|
155
|
+
crm comment create --task tsk_abc --kind decision \
|
|
156
|
+
--body "Cerrado, ver diff" --file ./after.png
|
|
157
|
+
|
|
158
|
+
crm chat send "$TID" --body "captura del 404" --file ./bug.png
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Reglas:
|
|
162
|
+
|
|
163
|
+
- Máx **10 MB por archivo** (rechazo local antes de tocar la red).
|
|
164
|
+
- Aviso en stderr desde **2 MB** (`[AVISO] ... la subida puede tardar.`).
|
|
165
|
+
- En `task update` la lista de adjuntos es **REEMPLAZO**, no merge. Usa
|
|
166
|
+
`--clear-files` para vaciar; pasa los antiguos junto con los nuevos si
|
|
167
|
+
quieres conservarlos.
|
|
168
|
+
- `--body` se vuelve opcional cuando hay `--file`.
|
|
169
|
+
|
|
170
|
+
## Flags globales
|
|
171
|
+
|
|
172
|
+
Disponibles en cada comando:
|
|
173
|
+
|
|
174
|
+
- `--json` — envoltura JSON completa (por defecto).
|
|
175
|
+
- `--quiet` — solo `data`.
|
|
176
|
+
- `--ids-only` — un id por línea.
|
|
177
|
+
- `--count` — un único entero.
|
|
178
|
+
- `--markdown` — resumen legible (no es JSON).
|
|
179
|
+
- `--jq <expr>` — jq mini (`.a`, `.a.b`, `.a[]`, `.a[].b`).
|
|
180
|
+
- `--shadow` — fuerza que la escritura aterrice como propuesta pendiente de
|
|
181
|
+
revisión humana.
|
|
182
|
+
- `--wait-for-approval --timeout 30m` — bloquea hasta que un humano decida.
|
|
183
|
+
- `--idempotency-key <key>` — idempotency key estable (automática en escrituras).
|
|
184
|
+
|
|
185
|
+
## Seguridad
|
|
186
|
+
|
|
187
|
+
- Sin scripts `preinstall` / `postinstall` / `install` — nada que se ejecute al
|
|
188
|
+
instalar el paquete.
|
|
189
|
+
- Auth por flujo de dispositivo: no se comparten secretos entre máquinas; el
|
|
190
|
+
access token caduca en 1 h y el refresh token rota en cada uso.
|
|
191
|
+
- Archivo de credenciales con permisos `0600`, aislado por perfil.
|
|
192
|
+
- Publicación con atestación de procedencia (`npm publish --provenance`) para
|
|
193
|
+
que se pueda verificar el origen del tarball.
|
|
194
|
+
|
|
195
|
+
## Licencia
|
|
196
|
+
|
|
197
|
+
MIT — ver [LICENSE](./LICENSE).
|
package/SKILL.md
CHANGED
|
@@ -232,7 +232,7 @@ Reglas:
|
|
|
232
232
|
- **Cuándo NO usar noindex:** para arreglar una canibalización (se arregla con contenido y enlaces), en una página con clics que la tarea no dice expresamente que hay que quitar, ni "por si acaso". Sí: páginas vacías, duplicadas o de servicio que no deben salir, y siempre porque lo pide la tarea.
|
|
233
233
|
- **Canonical:** URL absoluta del mismo dominio que responda 200 sin redirigir y no tenga noindex; si no, se bloquea. Un canonical a la propia página equivale al automático. No mezcles noindex y canonical a otra URL en la misma página (se avisa).
|
|
234
234
|
- Volver a `index` o `default` no pide permiso: la página tarda en volver a Google; puedes pedir la indexación en Search Console.
|
|
235
|
-
- **Fuera de alcance:** cambiar la URL/slug, precios, stock, borrar. Eso va por tarea a quien corresponda. Las redirecciones 301 del blog sí se hacen desde aquí (abajo).
|
|
235
|
+
- **Fuera de alcance:** cambiar la URL/slug, precios, stock (se puede leer, no cambiar), borrar. Eso va por tarea a quien corresponda. Las redirecciones 301 del blog sí se hacen desde aquí (abajo).
|
|
236
236
|
|
|
237
237
|
#### Redirecciones 301 del blog (`crm site redirect`)
|
|
238
238
|
|
|
@@ -265,6 +265,7 @@ Antes de proponer un cambio, mira qué dicen los datos de esa página. Tres fuen
|
|
|
265
265
|
|---|---|---|
|
|
266
266
|
| ¿Por qué búsquedas sale esta página y en qué posición? ¿Qué página gana una keyword? | Search Console | `crm gsc query --property <id> --dimension query --filters "page equals <url>; country equals esp; device equals mobile"` (y `--dimension page --filters "query equals <kw>; …"`) |
|
|
267
267
|
| ¿Cuánto vende esta ficha o categoría? ¿Qué fichas facturan más? | Ventas de la tienda | `crm site sales --url <url>` · `crm site sales --top 50 [--category <id>] --connection <id>` |
|
|
268
|
+
| ¿Hay stock de esta ficha? ¿Qué fichas de esta categoría están agotadas? ¿Qué packs faltan? (solo tiendas con stock real) | Stock de la tienda | `crm site stock --url <url>` · `crm site stock --url <categoría> --agotados` · `crm site stock --url <categoría> --combinaciones-agotadas --combinaciones` |
|
|
268
269
|
| ¿Cómo se comporta la gente en la página (sesiones, interacción, tiempo)? | Analytics (GA4) | `crm ga4 query --property <id> --dimensions pagePath --metrics sessions,engagementRate,averageSessionDuration,userEngagementDuration,screenPageViews,bounceRate --filters "pagePath equals /ruta/"` |
|
|
269
270
|
|
|
270
271
|
**Ventas (`crm site sales`).** Las suma el CRM cada noche desde el webservice de la tienda, sin datos de clientes:
|
|
@@ -272,10 +273,18 @@ Antes de proponer un cambio, mira qué dicen los datos de esa página. Tres fuen
|
|
|
272
273
|
- De una ficha: 28 y 90 días (hasta ayer) con su interanual (mismas fechas de hace 52 semanas) y su puesto por facturación dentro de su categoría por defecto. De una categoría: la suma de todas las fichas asociadas a ella o a sus subcategorías, como las lista la tienda (no solo las que la tienen por defecto; cada ficha cuenta una vez), y sus 10 fichas que más facturan. `crm site get` de una ficha o categoría ya trae el resumen de 90 días en `sales`.
|
|
273
274
|
- En sumas de varias fichas, `orders` cuenta pedidos por ficha; la facturación y las unidades son exactas.
|
|
274
275
|
- Si `previousYear.complete` es `false`, la tienda no tiene cargado el año pasado entero para esa ventana y el interanual sale `null`: no lo calcules a mano con datos a medias.
|
|
275
|
-
- **Nunca decidas con
|
|
276
|
+
- **Nunca decidas con la facturación de Analytics.** Para dinero, la tienda.
|
|
276
277
|
- Úsalas para priorizar (qué fichas o categorías trabajar primero), para elegir el destino de un enlace cuando dos páginas compiten y para medir: la revisión de métricas de la tarea añade las ventas de sus fichas y categorías antes y después, con el interanual.
|
|
277
278
|
- Si `available: false`, la tienda no da permiso de lectura de pedidos o aún no se han cargado: dilo en la tarea y sigue con Search Console.
|
|
278
279
|
|
|
280
|
+
**Stock (`crm site stock`).** Solo en tiendas donde el stock es real y su conexión lo tiene activado (growbaratochile.cl). En growbarato.net no lo es: el comando lo dice y no devuelve nada. Se lee en el momento, no se guarda:
|
|
281
|
+
- De una ficha: unidades totales, unidades por combinación (formato, tamaño, pack de semillas…), `combinationCounts` (cuántas combinaciones y cuántas agotadas) y `outOfStock.policy` (`deny`: agotada no se puede comprar; `allow`: se puede comprar sin stock; `default`: lo de la tienda). `crm site get` de una ficha ya trae el total en `stock`.
|
|
282
|
+
- De una categoría: sus fichas activas con su stock total y `combinations` (total, con stock y agotadas), primero las agotadas (las que más venden arriba, con las ventas de 90 días si están cargadas) y luego de menos a más stock. El resumen cuenta las combinaciones de la categoría, las agotadas y las fichas que tienen stock pero algún pack a cero.
|
|
283
|
+
- Filtros de categoría: `--agotados` deja solo las fichas sin stock; `--combinaciones-agotadas`, las que tienen alguna combinación agotada (incluidas las agotadas del todo); `--combinaciones` añade a cada ficha sus combinaciones con nombre y unidades; `--inactivos` añade las desactivadas.
|
|
284
|
+
- **Una ficha con stock puede tener packs agotados** (en semillas es lo normal): si la acción empuja un formato concreto, mira sus combinaciones, no solo el total.
|
|
285
|
+
- **Mira el stock antes de proponer una acción sobre una ficha o categoría** (enlazarla, destacarla, optimizarla, empujarla en un post): una ficha agotada no es buen destino. Si la ficha clave de la tarea está agotada, dilo en la tarea antes de seguir.
|
|
286
|
+
- Solo lectura: cambiar el stock no es cosa del CRM.
|
|
287
|
+
|
|
279
288
|
**Analytics (`crm ga4 query`).** Para comportamiento, no para dinero:
|
|
280
289
|
- Sirve para ver si una página con tráfico engancha (tasa de interacción, tiempo de interacción, páginas vistas) y comparar antes y después de un cambio de contenido.
|
|
281
290
|
- Páginas con muchas sesiones y poca interacción son candidatas a mejorar el contenido o la intención; páginas con buena interacción y pocas sesiones, a mejorar el title o el enlazado.
|
|
@@ -667,6 +676,11 @@ crm skill push my-playbook --note "primera revisión" --publish # body+frontma
|
|
|
667
676
|
crm skill archive my-playbook # hide from library
|
|
668
677
|
crm skill restore my-playbook # un-archive
|
|
669
678
|
|
|
679
|
+
# Work guides — the /dashboard/guias library (Roilab internal + per client). Read-only, staff only
|
|
680
|
+
crm guide list --q traductor --quiet # search title, summary and body
|
|
681
|
+
crm guide list --area contenido # by library area (partial match)
|
|
682
|
+
crm guide get <slug> --jq .data.body # published markdown; --draft for the draft
|
|
683
|
+
|
|
670
684
|
# Chat — read threads, post messages, react, attach files (max 10 MB each)
|
|
671
685
|
crm chat list --scope client --client cli_abc
|
|
672
686
|
crm chat get <threadId> --message-limit 50 # metadata + recent msgs
|