@roilab/crm-cli 0.18.0 → 0.21.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 +114 -0
- package/LICENSE +21 -21
- package/README.md +156 -119
- package/SKILL.md +116 -4
- package/SURFACE.txt +84 -24
- package/dist/bin/crm.js +11 -6
- package/dist/bin/crm.js.map +1 -1
- package/dist/src/commands/change.js +314 -0
- package/dist/src/commands/change.js.map +1 -0
- package/dist/src/commands/doc.js +21 -7
- package/dist/src/commands/doc.js.map +1 -1
- package/dist/src/commands/generic.js +76 -39
- package/dist/src/commands/generic.js.map +1 -1
- package/dist/src/commands/options.js +8 -1
- package/dist/src/commands/options.js.map +1 -1
- package/dist/src/commands/review.js +1 -1
- package/dist/src/commands/review.js.map +1 -1
- package/dist/src/commands/site.js +268 -0
- package/dist/src/commands/site.js.map +1 -0
- package/dist/src/commands/task-verify.js +197 -0
- package/dist/src/commands/task-verify.js.map +1 -0
- package/dist/src/commands/task.js +15 -28
- package/dist/src/commands/task.js.map +1 -1
- package/dist/src/transport/usage.js +137 -0
- package/dist/src/transport/usage.js.map +1 -0
- package/dist/src/types.js +7 -1
- package/dist/src/types.js.map +1 -1
- package/package.json +58 -58
- package/skill-bundles/tools/ahrefs-tool/SKILL.md +5 -5
- package/skill-bundles/tools/brightlocal-tool/SKILL.md +5 -5
- package/skill-bundles/tools/dataforseo-tool/SKILL.md +5 -5
- package/skill-bundles/tools/google-analytics-tool/SKILL.md +5 -5
- package/skill-bundles/tools/google-search-console-tool/SKILL.md +5 -5
- package/skill-bundles/tools/local-falcon-tool/SKILL.md +5 -5
- package/skill-bundles/tools/localseodata-tool/SKILL.md +5 -5
- package/skill-bundles/tools/lsa-spy-tool/SKILL.md +5 -5
- package/skill-bundles/tools/screaming-frog-tool/SKILL.md +5 -5
- package/skill-bundles/tools/semrush-tool/SKILL.md +5 -5
- package/skill-bundles/tools/serpapi-tool/SKILL.md +5 -5
- package/skill-bundles/tools/task-preflight/SKILL.md +157 -157
- package/skill-bundles/tools/whitespark-tool/SKILL.md +5 -5
- package/dist/src/commands/marketplace.js +0 -158
- package/dist/src/commands/marketplace.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,120 @@ Todos los cambios notables se documentan aquí. El formato sigue
|
|
|
4
4
|
[Keep a Changelog](https://keepachangelog.com/es/) y el versionado es
|
|
5
5
|
[SemVer](https://semver.org/lang/es/).
|
|
6
6
|
|
|
7
|
+
## [Sin publicar]
|
|
8
|
+
|
|
9
|
+
## [0.21.0] — 2026-11-09
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- **`crm site rules` — reglas de publicación de una web.** Devuelve el perfil
|
|
14
|
+
del dominio, las normas propias de la web, las comprobaciones y el texto
|
|
15
|
+
completo de las skills y documentos de conocimiento que aplican, con su
|
|
16
|
+
versión. `crm site update` no escribe si no se ha leído la versión vigente en
|
|
17
|
+
las últimas 24 horas, bloquea lo que las incumple de forma medible (longitud
|
|
18
|
+
máxima de title y meta, términos prohibidos que introduce el cambio) y avisa
|
|
19
|
+
del resto. `crm site get` dice si ya se han leído (`rules.readByYou`).
|
|
20
|
+
- **`crm site update --author <id>`** (WordPress): cambia el autor de la
|
|
21
|
+
entrada; si no es el habitual de la web, avisa.
|
|
22
|
+
|
|
23
|
+
## [0.20.0] — 2026-11-09
|
|
24
|
+
|
|
25
|
+
### Added
|
|
26
|
+
|
|
27
|
+
- **`crm site` — cambiar la tienda y el blog desde el CRM.** `list`, `test`,
|
|
28
|
+
`get` y `update` sobre las webs conectadas en la ficha del dominio
|
|
29
|
+
(PrestaShop por webservice, WordPress por contraseña de aplicación). La
|
|
30
|
+
credencial no sale del servidor. `update` exige `--task` del mismo dominio,
|
|
31
|
+
escribe solo lo que cambia, vuelve a leer para confirmar lo guardado,
|
|
32
|
+
comprueba la página publicada y crea el registro de cambios con el antes y el
|
|
33
|
+
después reales. `--dry-run` enseña el diff. Scopes nuevos `sites:read` y
|
|
34
|
+
`sites:write` (staff).
|
|
35
|
+
- **`crm task tracking get|set` — seguimiento de URLs de una tarea.** Cada
|
|
36
|
+
registro de cambios (web, CLI o conector) mete su URL; el ámbito de la
|
|
37
|
+
revisión de métricas puede ser la lista de URLs, un patrón de página
|
|
38
|
+
(`--pattern '\.html$'`) o el dominio entero (`--domain`). Al completar la
|
|
39
|
+
tarea la revisión se programa sola a 28 días del cierre (`--verify-days`,
|
|
40
|
+
`--no-auto-verify`).
|
|
41
|
+
- **`--completed-at <date>` en `crm task update` y `crm task create`.** Fija la
|
|
42
|
+
fecha de completado (`YYYY-MM-DD` o ISO) para fechar trabajo cerrado fuera del
|
|
43
|
+
CRM. Solo staff, la tarea tiene que quedar en done (en la misma llamada vale
|
|
44
|
+
`--status done` o `--column` de done) y no admite fechas futuras. Una fecha
|
|
45
|
+
sin hora se guarda a las 12:00 UTC para que caiga en el mismo día en España.
|
|
46
|
+
Queda en el historial de la tarea.
|
|
47
|
+
|
|
48
|
+
### Fixed
|
|
49
|
+
|
|
50
|
+
- **Revisiones de métricas con regex o listas de URLs medían cero.** Cuando la
|
|
51
|
+
medición iba directa a la API de Search Console, el operador se traducía dos
|
|
52
|
+
veces y `regex`, `not_regex`, `not_equals` y `not_contains` acababan como
|
|
53
|
+
`contains` literal; una lista de URLs se buscaba como un único texto. Ahora
|
|
54
|
+
los operadores se respetan y las listas se piden en tandas de regex.
|
|
55
|
+
- **La ayuda de `crm change log` decía que `--date` alimentaba la medición
|
|
56
|
+
antes/después.** Solo coloca el marcador en las gráficas; la revisión de
|
|
57
|
+
métricas cuenta desde que se completa la tarea.
|
|
58
|
+
- **`crm review approve task <id>` sobre una tarea con la marca REVISAR daba
|
|
59
|
+
`INTERNAL`.** Solo entendía propuestas en espera (`approvalStatus: pending`);
|
|
60
|
+
una tarea de agente ya aplicada con `reviewRequired` fallaba con "Task is not
|
|
61
|
+
pending". Ahora la acepta igual que el botón Aceptar de la web (mismo
|
|
62
|
+
historial y mismos avisos). Si no hay nada que aprobar devuelve `CONFLICT`
|
|
63
|
+
con el motivo, y los errores de ámbito o rol salen con su código
|
|
64
|
+
(`FORBIDDEN_SCOPE`, `FORBIDDEN_ROLE`, `NOT_FOUND`) en vez de `INTERNAL`.
|
|
65
|
+
- **Crear una tarea con `--status done` dejaba la fecha de completado vacía.**
|
|
66
|
+
Ahora se estampa al crearla, como hace la web.
|
|
67
|
+
|
|
68
|
+
### Removed
|
|
69
|
+
|
|
70
|
+
- **`crm marketplace` (compare, domain, providers, import, scrape), `crm offer
|
|
71
|
+
list-tasks` y `crm task link-offer`.** El comparador de precios de enlaces y
|
|
72
|
+
las ofertas se fueron del CRM a pwn-control (`https://pwn.roilab.es/mercado`).
|
|
73
|
+
Los endpoints REST/MCP equivalentes (`/marketplace/*`, `/offers/*`) también
|
|
74
|
+
desaparecen, junto con los scopes `marketplace:read` y `marketplace:write`.
|
|
75
|
+
- `crm task complete-with-evidence --asset` solo acepta `backlink:<id>`.
|
|
76
|
+
|
|
77
|
+
## [0.19.0] — 2026-08-04
|
|
78
|
+
|
|
79
|
+
### Fixed
|
|
80
|
+
|
|
81
|
+
- **`crm change list` ya no exige `--domain`.** Era una restricción del CLI, no
|
|
82
|
+
del backend: la consulta sin dominio siempre estuvo soportada (rama
|
|
83
|
+
`by_workspace` + filtro de URL exacta). Al ser `requiredOption`, un
|
|
84
|
+
`crm change list --url <url>` fallaba por stderr y con `--quiet 2>/dev/null`
|
|
85
|
+
dejaba stdout vacío — indistinguible de "cero cambios". Ahora todos los
|
|
86
|
+
filtros son opcionales y combinables.
|
|
87
|
+
- **`--since` se perdía en silencio** en `crm change list`, `crm recall` y
|
|
88
|
+
`crm backlink lost`. Cuando la raíz declara el mismo flag que el subcomando,
|
|
89
|
+
commander guarda el valor en la raíz aunque lo escribas después del verbo, así
|
|
90
|
+
que `opts.since` llegaba `undefined` y el filtro nunca viajaba: devolvía más
|
|
91
|
+
filas de las pedidas, sin ningún error. Ahora los tres leen de `readFlags`,
|
|
92
|
+
que sí recorre la cadena. La trampa queda documentada en `options.ts`.
|
|
93
|
+
- **Un id de otra tabla ya no devuelve "Server Error".** `--domain` / `--task`
|
|
94
|
+
con un id que no es de esa tabla (o el host en vez del id) rebotaban contra el
|
|
95
|
+
validador `v.id()` de Convex, y producción censura ese error a un 500 genérico.
|
|
96
|
+
Ahora se normalizan con `ctx.db.normalizeId` y el fallo sale como
|
|
97
|
+
`INVALID_INPUT` con el nombre del flag y qué se esperaba.
|
|
98
|
+
- **Los errores de argumentos respetan el contrato de envoltura JSON.** Un
|
|
99
|
+
fallo de parseo de commander (opción obligatoria ausente, opción desconocida,
|
|
100
|
+
comando mal escrito) salía como texto plano por stderr con stdout vacío,
|
|
101
|
+
saltándose la promesa de "envoltura JSON siempre". Ahora sale como
|
|
102
|
+
`{ ok: false, error: { code: "USAGE", … } }` **por stdout** con exit code
|
|
103
|
+
`64`, mensaje en español y `details.raw` con el texto original de commander.
|
|
104
|
+
`--help` y `--version` siguen saliendo con código 0 y su salida de siempre.
|
|
105
|
+
|
|
106
|
+
### Added
|
|
107
|
+
|
|
108
|
+
- **`crm change list --task <id>`.** Convex ya tenía `changeEvents.list({taskId})`
|
|
109
|
+
con índice `by_task` — es lo que pinta el cajón de la tarea — pero el CLI no
|
|
110
|
+
lo exponía. Es el filtro más barato de los cuatro.
|
|
111
|
+
- Endpoint nuevo `GET /api/v1/changes`: mismas filas que
|
|
112
|
+
`GET /api/v1/domains/:id/changes` pero con todos los filtros opcionales
|
|
113
|
+
(`domainId`, `taskId`, `url`, `sinceIso`). El endpoint por dominio se queda
|
|
114
|
+
para no romper a nadie y también acepta `taskId`.
|
|
115
|
+
|
|
116
|
+
### Notes
|
|
117
|
+
|
|
118
|
+
- Despliega el servidor **antes** de publicar este CLI: `crm change list` pasa a
|
|
119
|
+
llamar a `/changes`, que no existe en despliegues anteriores.
|
|
120
|
+
|
|
7
121
|
## [0.18.0] — 2026-07-29
|
|
8
122
|
|
|
9
123
|
### Added
|
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 ROILab Intelligence
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ROILab Intelligence
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,119 +1,156 @@
|
|
|
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
|
-
npm i -g @roilab/crm-cli@latest
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
El propio CLI comprueba una vez al día si hay una versión nueva en npm y avisa
|
|
36
|
-
por stderr. Para forzar la comprobación, ejecuta `crm doctor`.
|
|
37
|
-
|
|
38
|
-
## Primer login (30 segundos)
|
|
39
|
-
|
|
40
|
-
```bash
|
|
41
|
-
crm auth login --device-name mi-portatil
|
|
42
|
-
# Abre la URL que aparece en el navegador, aprueba.
|
|
43
|
-
crm auth whoami
|
|
44
|
-
crm doctor
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
El CLI guarda tokens rotativos en `~/.config/crm/credentials.json` (modo `0600`).
|
|
48
|
-
Nunca se escribe una API key en claro en disco por esta vía.
|
|
49
|
-
|
|
50
|
-
## Comandos
|
|
51
|
-
|
|
52
|
-
```bash
|
|
53
|
-
crm recall https://example.com/pricing
|
|
54
|
-
crm task list --status todo --domain dom_xyz --limit 20
|
|
55
|
-
crm task create --title "Arreglar H1 en /pricing" --domain dom_xyz --shadow
|
|
56
|
-
crm
|
|
57
|
-
crm
|
|
58
|
-
crm
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
crm
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
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
|
+
npm i -g @roilab/crm-cli@latest
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
El propio CLI comprueba una vez al día si hay una versión nueva en npm y avisa
|
|
36
|
+
por stderr. Para forzar la comprobación, ejecuta `crm doctor`.
|
|
37
|
+
|
|
38
|
+
## Primer login (30 segundos)
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
crm auth login --device-name mi-portatil
|
|
42
|
+
# Abre la URL que aparece en el navegador, aprueba.
|
|
43
|
+
crm auth whoami
|
|
44
|
+
crm doctor
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
El CLI guarda tokens rotativos en `~/.config/crm/credentials.json` (modo `0600`).
|
|
48
|
+
Nunca se escribe una API key en claro en disco por esta vía.
|
|
49
|
+
|
|
50
|
+
## Comandos
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
crm recall https://example.com/pricing
|
|
54
|
+
crm task list --status todo --domain dom_xyz --limit 20
|
|
55
|
+
crm task create --title "Arreglar H1 en /pricing" --domain dom_xyz --shadow
|
|
56
|
+
crm task update tsk_abc --status done --completed-at 2026-10-28
|
|
57
|
+
crm review approve task tsk_abc # aprueba una propuesta o quita la marca REVISAR
|
|
58
|
+
crm comment create --task tsk_abc --body "Desplegado en prod" --kind agent_log
|
|
59
|
+
crm domain metrics dom_xyz --start 2026-03-01 --end 2026-04-01 --markdown
|
|
60
|
+
crm review list --mine
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`crm --help` imprime todos los sustantivos; `crm <noun> --help` imprime los
|
|
64
|
+
verbos; la documentación completa vive en la app, pestaña **Documentación**, que
|
|
65
|
+
se auto-genera desde el registro de endpoints — siempre refleja la versión
|
|
66
|
+
servida.
|
|
67
|
+
|
|
68
|
+
## Cambiar la tienda y el blog (`crm site`)
|
|
69
|
+
|
|
70
|
+
Con las credenciales guardadas en el CRM (ficha del dominio → Conexiones con la
|
|
71
|
+
web) se leen y cambian el H1, el meta title, la meta description y el contenido
|
|
72
|
+
de la tienda PrestaShop y del blog WordPress. La credencial no sale del
|
|
73
|
+
servidor y cada cambio queda en el registro de cambios de su tarea.
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
crm site list # webs que puedes usar
|
|
77
|
+
crm site rules --url https://www.tienda.com/ # reglas de publicación (obligatorio antes de escribir)
|
|
78
|
+
crm site get --url https://www.tienda.com/598-cbd # valores actuales
|
|
79
|
+
crm site update --task tsk_abc --url https://www.tienda.com/598-cbd \
|
|
80
|
+
--meta-title-file title.txt --meta-desc-file desc.txt --dry-run
|
|
81
|
+
crm site update --task tsk_abc --url https://www.tienda.com/598-cbd \
|
|
82
|
+
--meta-title-file title.txt --meta-desc-file desc.txt --note "por qué"
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
`update` escribe solo lo que cambia, vuelve a leer la página para confirmar lo
|
|
86
|
+
guardado, comprueba la página publicada y registra el cambio con el antes y el
|
|
87
|
+
después reales. No escribe si no has leído en las últimas 24 horas la versión
|
|
88
|
+
vigente de las reglas de la web (perfil del dominio, normas, skills y documentos),
|
|
89
|
+
y bloquea lo que las incumple de forma medible.
|
|
90
|
+
|
|
91
|
+
## Seguimiento de URLs (`crm task tracking`)
|
|
92
|
+
|
|
93
|
+
Cada cambio registrado mete su URL en el seguimiento de la tarea; al
|
|
94
|
+
completarla, la revisión de métricas se programa sola (28 días por defecto) y
|
|
95
|
+
mide esas URLs en Search Console. Para medir un grupo o el dominio entero:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
crm task tracking get tsk_abc
|
|
99
|
+
crm task tracking set tsk_abc --pattern '\.html$' # todas las fichas
|
|
100
|
+
crm task tracking set tsk_abc --domain
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Adjuntar archivos (`--file`)
|
|
104
|
+
|
|
105
|
+
`task create` / `task update` / `comment create` / `chat send` / `chat reply`
|
|
106
|
+
aceptan `--file <ruta>` (repetible). Es **un flag, no un subcomando** — no
|
|
107
|
+
existe `crm task attach` ni `crm upload`. El CLI sube cada archivo a Convex
|
|
108
|
+
storage en dos pasos y manda los `attachments[]` en la misma escritura.
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
crm task create --title "Migración H1" --domain dom_xyz \
|
|
112
|
+
--file ./brief.pdf --file ./screenshot.png
|
|
113
|
+
|
|
114
|
+
crm comment create --task tsk_abc --kind decision \
|
|
115
|
+
--body "Cerrado, ver diff" --file ./after.png
|
|
116
|
+
|
|
117
|
+
crm chat send "$TID" --body "captura del 404" --file ./bug.png
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Reglas:
|
|
121
|
+
|
|
122
|
+
- Máx **10 MB por archivo** (rechazo local antes de tocar la red).
|
|
123
|
+
- Aviso en stderr desde **2 MB** (`[AVISO] ... la subida puede tardar.`).
|
|
124
|
+
- En `task update` la lista de adjuntos es **REEMPLAZO**, no merge. Usa
|
|
125
|
+
`--clear-files` para vaciar; pasa los antiguos junto con los nuevos si
|
|
126
|
+
quieres conservarlos.
|
|
127
|
+
- `--body` se vuelve opcional cuando hay `--file`.
|
|
128
|
+
|
|
129
|
+
## Flags globales
|
|
130
|
+
|
|
131
|
+
Disponibles en cada comando:
|
|
132
|
+
|
|
133
|
+
- `--json` — envoltura JSON completa (por defecto).
|
|
134
|
+
- `--quiet` — solo `data`.
|
|
135
|
+
- `--ids-only` — un id por línea.
|
|
136
|
+
- `--count` — un único entero.
|
|
137
|
+
- `--markdown` — resumen legible (no es JSON).
|
|
138
|
+
- `--jq <expr>` — jq mini (`.a`, `.a.b`, `.a[]`, `.a[].b`).
|
|
139
|
+
- `--shadow` — fuerza que la escritura aterrice como propuesta pendiente de
|
|
140
|
+
revisión humana.
|
|
141
|
+
- `--wait-for-approval --timeout 30m` — bloquea hasta que un humano decida.
|
|
142
|
+
- `--idempotency-key <key>` — idempotency key estable (automática en escrituras).
|
|
143
|
+
|
|
144
|
+
## Seguridad
|
|
145
|
+
|
|
146
|
+
- Sin scripts `preinstall` / `postinstall` / `install` — nada que se ejecute al
|
|
147
|
+
instalar el paquete.
|
|
148
|
+
- Auth por flujo de dispositivo: no se comparten secretos entre máquinas; el
|
|
149
|
+
access token caduca en 1 h y el refresh token rota en cada uso.
|
|
150
|
+
- Archivo de credenciales con permisos `0600`, aislado por perfil.
|
|
151
|
+
- Publicación con atestación de procedencia (`npm publish --provenance`) para
|
|
152
|
+
que se pueda verificar el origen del tarball.
|
|
153
|
+
|
|
154
|
+
## Licencia
|
|
155
|
+
|
|
156
|
+
MIT — ver [LICENSE](./LICENSE).
|
package/SKILL.md
CHANGED
|
@@ -123,9 +123,20 @@ Errors **always** appear on stderr with full envelope, bypassing `--jq`. Exit co
|
|
|
123
123
|
--body "Cerrado: H1 reemplazado, A/B +12% CTR a 14d (ver crm change list)"
|
|
124
124
|
```
|
|
125
125
|
|
|
126
|
+
**SEO work whose effect shows up weeks later** (metas, contenido, enlazado interno, enlaces): complete it AND schedule the metric review in one step, instead of a bare `--status done`. On that day staff are notified and the task enters the review queue with a before/after snapshot (see § Revisión de métricas):
|
|
127
|
+
```bash
|
|
128
|
+
crm task verify schedule tsk_abc --complete --in 30 --criteria "CTR de /categoria/x por encima del 3 % (hoy 1,9 %)"
|
|
129
|
+
```
|
|
130
|
+
Defaults: 30 días; 60 para contenido. Write `--criteria` as a measurable target with its current baseline — it is what the reviewer (human or agent) checks first.
|
|
131
|
+
|
|
132
|
+
**Work closed outside the CRM** (done last week, logged today): date it with `--completed-at` instead of leaving today's stamp. Staff keys only; the task must end the call in done, and future dates are rejected:
|
|
133
|
+
```bash
|
|
134
|
+
crm task update tsk_abc --status done --completed-at 2026-10-23
|
|
135
|
+
```
|
|
136
|
+
|
|
126
137
|
4. **Use `reviewRequired`**. Your task creates default to `reviewRequired=true` — the human sees them in a dedicated inbox section. Only pass `--no-review` for low-stakes rework (e.g. re-filing a recurring instance). (The flag has only been wired end-to-end since 0.6.0 — earlier CLIs sent it but the server stripped it.)
|
|
127
138
|
|
|
128
|
-
**Read side — when you see `reviewRequired: true` on a task you didn't create**: treat it as tentative. The row is live but a human hasn't acknowledged it yet, and may still edit, reassign, or reject the framing. Don't build downstream work that assumes it's settled (no offers linked to it, no auto-complete on its goals, no marking siblings as duplicates of it).
|
|
139
|
+
**Read side — when you see `reviewRequired: true` on a task you didn't create**: treat it as tentative. The row is live but a human hasn't acknowledged it yet, and may still edit, reassign, or reject the framing. Don't build downstream work that assumes it's settled (no offers linked to it, no auto-complete on its goals, no marking siblings as duplicates of it). Don't approve your own writes: only humans decide to clear the flag. `crm review approve task <id>` does clear it (same as the web Aceptar button), so run it only when a human explicitly asks you to approve that task. If you're blocked waiting, leave a `--kind decision` agent_log comment, don't change status. Filter the queue with `crm task list --review-pending` (or `GET /tasks?reviewRequired=true`).
|
|
129
140
|
|
|
130
141
|
5. **Every write gets an idempotency key**. The CLI autogenerates one per invocation, so retries within a single command are safe. If you're orchestrating retries across invocations, pass `--idempotency-key <ulid>` so the retry replays instead of double-creating.
|
|
131
142
|
|
|
@@ -160,6 +171,107 @@ Errors **always** appear on stderr with full envelope, bypassing `--jq`. Exit co
|
|
|
160
171
|
|
|
161
172
|
**Do NOT confuse this with `[[feedback_task_refs_use_chip_syntax]]`**: inside task descriptions, comments, and chat bodies you still use `#[Title](taskId)` chips, never raw dashboard URLs. The dashboard URL goes only in your chat reply to the human reviewing your work — that is where they need a one-click destination.
|
|
162
173
|
|
|
174
|
+
8. **Cada cambio on-page que publiques, regístralo en su tarea.** Si lo aplicas con `crm site update` el registro se crea solo (con el antes y el después reales). Si lo publicas por otra vía (back office, editor de WordPress), usa `crm change log`. El registro pinta el marcador en las gráficas y mete la URL en el seguimiento de la tarea, que es lo que medirá su revisión de métricas (ver «Cambiar la tienda y el blog»).
|
|
175
|
+
- **Nunca registres un cambio sin verificarlo en vivo antes.** Abre la URL publicada (sin caché) y comprueba que el valor nuevo está ahí. Si no lo ves, no lo registres: arregla la publicación o avisa.
|
|
176
|
+
- **Una URL por registro.** Varios cambios en la misma URL → un solo `crm change log` con `--items-file`; varias URLs → un comando por URL.
|
|
177
|
+
- **`--date` = día real de publicación**, no el de hoy si lo publicaste antes.
|
|
178
|
+
- Metas y H1: `--before` (valor anterior) y `--after` (nuevo). Contenido largo: `--type content` con `--note "qué cambió"` y, si quieres, `--after-file`; no hace falta pegar el texto entero. Textos con acentos o saltos de línea, siempre por fichero (`--before-file` / `--after-file` / `--note-file`).
|
|
179
|
+
- Lotes (CSV de URLs): un comando por fila en un bucle, con `--idempotency-key` estable (p. ej. `<taskId>-<n.º de fila>`) para que reintentar el bucle no duplique filas.
|
|
180
|
+
- No hay `--shadow` ni revisión para los cambios: se guardan directos. Si tu key tiene "Change events" en shadow, el servidor responde `BUSINESS_RULE` y hay que cambiar la política.
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
crm change log --task ms7abc --url https://tienda.com/zapatillas \
|
|
184
|
+
--type metaTitle --before "Zapatillas | Tienda" --after-file title.txt --date 2026-10-19
|
|
185
|
+
crm change log --task ms7abc --url https://tienda.com/guia-tallas \
|
|
186
|
+
--type content --note "Reescrita la sección de tallas y añadida tabla de equivalencias"
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
## Cambiar la tienda y el blog (`crm site`)
|
|
190
|
+
|
|
191
|
+
El CRM guarda cifradas las credenciales de la tienda (PrestaShop, webservice) y del blog (WordPress, contraseña de aplicación) de cada dominio. Tú nunca las ves: `crm site` habla con la web desde el servidor. Una conexión la usan owner/admin y los miembros autorizados en ella (que además tengan asignado el cliente).
|
|
192
|
+
|
|
193
|
+
**Reglas de publicación (obligatorio).** Cada web tiene sus reglas en el CRM: el perfil del dominio (posicionamiento, tono, audiencia, guía de contenidos), normas propias (por ejemplo, quién es el autor habitual del blog), comprobaciones y el texto completo de las skills y documentos de conocimiento que aplican. Léelas al empezar a trabajar con una web y aplícalas a todo lo que redactes:
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
crm site rules --url <url-de-la-web> # paquete completo + versión; deja constancia de la lectura (24 h)
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
`crm site get` te dice en `rules.readByYou` si ya tienes la versión vigente. `crm site update` **no escribe** si no la has leído en las últimas 24 horas o si las reglas han cambiado desde entonces: vuelve a leerlas. El servidor bloquea lo medible (title o meta por encima del máximo de la web, términos prohibidos que tu cambio introduce) y avisa del resto (longitud recomendada, enlaces nuevos a dominios no previstos, un autor distinto del habitual). Lo que no se puede medir (tono, estilo, datos de marca) depende de ti: es lo que traen las skills y los documentos.
|
|
200
|
+
|
|
201
|
+
**Flujo obligatorio para cada página:**
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
crm site rules --url <url> # al empezar con cada web (y si cambia la versión)
|
|
205
|
+
crm task get <taskId> # qué pide la tarea
|
|
206
|
+
crm recall <url> # trabajo previo sobre la URL
|
|
207
|
+
crm site get --url <url> --quiet > actual.json # valores de AHORA (h1, metaTitle, metaDescription, content, summary)
|
|
208
|
+
# … preparas los textos nuevos en ficheros UTF-8 …
|
|
209
|
+
crm site update --task <taskId> --url <url> --meta-title-file t.txt --meta-desc-file d.txt --dry-run # diff
|
|
210
|
+
crm site update --task <taskId> --url <url> --meta-title-file t.txt --meta-desc-file d.txt --note "por qué"
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Reglas:
|
|
214
|
+
- **`--task` siempre**, y la tarea tiene que ser del mismo dominio que la web. Sin tarea no se escribe.
|
|
215
|
+
- **Lee antes de escribir** (`crm site get`) y parte de ese texto para el contenido: `--content-file` sustituye el HTML entero.
|
|
216
|
+
- **Lee la respuesta:** `applied` (lo que la relectura confirma), `notApplied` (lo que la web no guardó; ej. un plugin que corta el guardado), `liveCheck` (`ok`, `cached` = la caché aún sirve lo viejo, `mismatch`, `unverifiable` = la página no responde 200) y `warnings`. Si hay `notApplied` o `mismatch`, dilo en la tarea; no lo des por hecho.
|
|
217
|
+
- **El registro de cambios se crea solo** con lo aplicado. No repitas con `crm change log`.
|
|
218
|
+
- **Campos:** `h1` (título del post o página, nombre del producto o la categoría, título del CMS), `metaTitle`, `metaDescription`, `content` (HTML: cuerpo del post, descripción del producto o de la categoría, contenido del CMS), `summary` (extracto en WP, descripción corta del producto, descripción adicional de abajo en la categoría) y, solo en WordPress, `author` (`--author <id>`; las reglas dicen cuál es el habitual, cámbialo solo si la tarea lo pide). Los CMS de PrestaShop no tienen `summary`.
|
|
219
|
+
- **Fuera de alcance:** URL/slug (exige redirección), noindex/canonical, precios, stock, borrar. Eso va por tarea a quien corresponda.
|
|
220
|
+
- **PrestaShop multitienda:** escribe en la tienda y el idioma de la conexión y conserva los demás idiomas. PrestaShop guarda el objeto entero y su filtro de HTML puede reescribir textos de otros idiomas (igual que desde el back office): sale en `warnings`.
|
|
221
|
+
- **Sin ráfagas.** Una página detrás de otra; hay servidores que bloquean la IP ante muchas peticiones seguidas.
|
|
222
|
+
- **URL que no se reconoce** (rutas propias de un módulo): usa `--ref product:<id>` / `category:<id>` / `cms:<id>` / `post:<id>` / `page:<id>` junto a `--url`.
|
|
223
|
+
|
|
224
|
+
### Seguimiento de URLs (`crm task tracking`)
|
|
225
|
+
|
|
226
|
+
Cada registro de cambios añade su URL al seguimiento de la tarea y la tarea queda vinculada a la propiedad GSC del dominio filtrada a esas URLs. Al completarla, la revisión de métricas se programa sola a 28 días del cierre (`--verify-days` para cambiarlo). Si el trabajo no es de URLs sueltas, cambia el ámbito:
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
crm task tracking get <taskId>
|
|
230
|
+
crm task tracking set <taskId> --pattern '\.html$' # todas las fichas (regex RE2 de GSC)
|
|
231
|
+
crm task tracking set <taskId> --pattern /blog/ --operator contains
|
|
232
|
+
crm task tracking set <taskId> --urls-file urls.txt # lista exacta (una por línea)
|
|
233
|
+
crm task tracking set <taskId> --domain # dominio entero
|
|
234
|
+
crm task tracking set <taskId> --no-auto-verify # programarla a mano
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
Las listas van como un solo filtro (GSC combina filtros con AND: diez `equals` darían cero). Las URLs se guardan con y sin barra final para que casen con cómo las tenga Search Console.
|
|
238
|
+
|
|
239
|
+
## Revisión de métricas (rutina diaria)
|
|
240
|
+
|
|
241
|
+
Una tarea SEO se **aplica** (se completa, `completedAt` = día del cambio) y se **revisa** N días después. Ese día el servidor:
|
|
242
|
+
1. la pasa a `due` y avisa a quien la programó y a sus responsables (solo equipo),
|
|
243
|
+
2. calcula la foto con Search Console en vivo sobre el ámbito de la tarea (URLs del seguimiento, `crm task tracking get`; si no hay, la propiedad vinculada; si no, el dominio). En `verification.snapshot.analysis`:
|
|
244
|
+
- **Métricas:** clics (todos los dispositivos); impresiones, CTR, posición y número de keywords (solo móvil: el escritorio de GB va inflado).
|
|
245
|
+
- **Comparaciones por métrica:** `pop` (antes → después, ventanas simétricas al día aplicado), `yoy` (después contra las mismas fechas de hace 52 semanas), `popLY` (el antes → después de hace un año: estacionalidad de esas URLs), `vsLastYear` (este año ajustado por el pasado), `controlPop` y `net` (efecto por encima del grupo de control). Volumen y CTR en tanto por uno; posición en diferencia absoluta (negativa = mejora).
|
|
246
|
+
- **Grupo de control:** la misma sección sin las URLs de la tarea (fichas, categorías o blog) o el resto del dominio; con el dominio entero no hay control y se usa el año anterior.
|
|
247
|
+
- **`noiseBand`** (variación semanal normal frente al control, en escala logarítmica), **`suggestion`** (veredicto propuesto por los clics netos, con un mínimo del 5 % y por encima del ruido; `inconclusive` con poco volumen o ruido de más de ±50 %), **`reasons`** (explicación en español), **`googleUpdates`** e **`otherChanges`** (otras tareas que tocaron esas URLs en las ventanas);
|
|
248
|
+
y las metas de ranking de la tarea,
|
|
249
|
+
3. la pone en la cola de la bandeja ("Revisiones de métricas").
|
|
250
|
+
|
|
251
|
+
Estados: `scheduled` → `due` → `proposed` (un agente dejó análisis) → `resolved` (una persona decidió). Veredictos: `positive` · `neutral` · `negative` · `inconclusive`.
|
|
252
|
+
|
|
253
|
+
**Rutina del agente** (una vez al día, o cuando te lo pidan):
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
crm task verify list # vencidas + propuestas, con la foto
|
|
257
|
+
crm task verify show tsk_abc # criterio, foto, metas, propuesta previa
|
|
258
|
+
crm task get tsk_abc # qué se hizo (descripción, dominio, propiedades)
|
|
259
|
+
crm change list --task tsk_abc # cambios on-page registrados y sus fechas
|
|
260
|
+
crm change list --domain <id> --since <iso> # otros cambios del dominio en la ventana (confusores)
|
|
261
|
+
crm recall <url> # historia de la URL (tareas, comentarios, enlaces)
|
|
262
|
+
crm gsc query --property <id> --dimension query --filters "page==<url>" ... # si la foto no basta
|
|
263
|
+
crm task verify resolve tsk_abc --verdict positive --note-file analisis.md
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
Reglas:
|
|
267
|
+
- **Tú solo propones.** Tu `resolve` deja la revisión en `proposed`; una persona la confirma (o cambia el veredicto) en la bandeja. No intentes cerrarla de otra forma ni reabrir la tarea tú: si el veredicto es `negative`, dilo en la nota y propón el siguiente paso; la persona decide si la reabre.
|
|
268
|
+
- **Solo cuando ya venció.** Antes de la fecha el servidor rechaza la propuesta: los datos aún no son comparables.
|
|
269
|
+
- **Parte de `analysis.suggestion` y `analysis.reasons`, pero compruébalos:** si `otherChanges` o `googleUpdates` explican el movimiento, o el control no es comparable, dilo y cambia el veredicto.
|
|
270
|
+
- **La nota es obligatoria y es el producto.** Qué métrica se movió, cuánto, contra qué ventana, si coincide con el criterio, y qué más pudo influir (estacionalidad, otros cambios del dominio en `crm change list`, actualizaciones de Google). Sin adornos: números y conclusión.
|
|
271
|
+
- **`inconclusive` es una respuesta válida** (pocos datos, ventana corta, ruido). Si crees que con más tiempo se verá, mejor `crm task verify snooze tsk_abc --in 14` que forzar un veredicto.
|
|
272
|
+
- **Foto vieja o sin datos** → `crm task verify measure tsk_abc` (máx. 1 vez/hora; Tinybird tiene cuota diaria) y vuelve a `show` en unos segundos.
|
|
273
|
+
- Todo esto es interno: nunca lo menciones en comentarios visibles para el cliente.
|
|
274
|
+
|
|
163
275
|
## Descubrir tableros (antes de colocar o mover tareas)
|
|
164
276
|
|
|
165
277
|
`crm board list` enumera los tableros del workspace (`_id`, `name`, `clientId`,
|
|
@@ -426,9 +538,9 @@ crm task create \
|
|
|
426
538
|
|
|
427
539
|
# Change events (log de cambios on-page): disponibles en cualquier tarea
|
|
428
540
|
# anclada a un dominio (task.domainId) — el backend rechaza tareas sin
|
|
429
|
-
# dominio. Lectura
|
|
430
|
-
# `crm change
|
|
431
|
-
|
|
541
|
+
# dominio. Lectura con `crm change list` (GET /changes); escritura con
|
|
542
|
+
# `crm change log` (POST /changes) — ver regla 8. Verifica en vivo antes.
|
|
543
|
+
crm change log --task ms7abc --type h1 --before "Zapatillas" --after "Zapatillas running hombre"
|
|
432
544
|
|
|
433
545
|
# Search across everything
|
|
434
546
|
crm search "meta title" --kind change --domain dom_xyz --limit 5
|