Merge pull request #97 from NerioVillalobos/metadelta-monitor-command

Metadelta monitor command

Author: NerioVillalobos

README.md

@@ -1,4 +1,4 @@
-> **Last update / Última actualización:** 2026-06-11 — `@nervill/metadelta` 0.11.8
+> **Last update / Última actualización:** 2026-06-11 — `@nervill/metadelta` 0.11.9
 
 # Metadelta Salesforce CLI Plugin
 
@@ -50,7 +50,7 @@ Created by **Nerio Villalobos** (<nervill@gmail.com>).
    ```bash
    sf plugins install github:NerioVillalobos/plugin-metadelta.git
    ```
-   Confirm installation with `sf plugins`, which should list `@nervill/metadelta 0.11.8`.
+   Confirm installation with `sf plugins`, which should list `@nervill/metadelta 0.11.9`.
 
 3. (Optional, for local development) Clone this repository and install dependencies:
    ```bash
@@ -63,7 +63,7 @@ Created by **Nerio Villalobos** (<nervill@gmail.com>).
    npm run build
    sf plugins link .
    ```
-   Confirm installation with `sf plugins`, which should list `@nervill/metadelta 0.11.8 (link)`.
+   Confirm installation with `sf plugins`, which should list `@nervill/metadelta 0.11.9 (link)`.
 
 ### Usage
 
@@ -380,13 +380,22 @@ Starts a temporary terminal monitor for Salesforce Core and Vlocity metadata dri
 sf metadelta monitor run --org DEV
 ```
 
+Options:
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--org`, `-o` | Alias or username of the target org. | Required |
+| `--interval` | Refresh interval in minutes. Values below `1` are normalized to `1`. | `5` |
+| `--scope` | Metadata source to monitor: `all`, `salesforce`, or `vlocity`. | `all` |
+| `--once` | Run one refresh cycle and exit after cleanup. Useful for validation. | `false` |
+
 The monitor creates `.metadelta-monitor/`, retrieves the current metadata snapshot, initializes a local-only Git repository as the diff engine, and refreshes every five minutes. `NEXT` shows the exact next refresh time instead of repainting a countdown. The first cycle creates the baseline and shows `STATUS: BASELINE CREATED`; later refreshes show added, modified, deleted, or renamed files. Full errors and Vlocity warnings are wrapped in a detail section and automatically pause UI repainting so the text can be selected/copied.
 
 The UI has two navigable sections. `SALESFORCE CORE / VLOCITY` groups changes by metadata type and shows the count, latest change date, and latest modifier for each type. `RECENT CHANGES` lists the session-cumulative component changes with the most recently detected items first. The arrow keys move the `>` selector across both sections; when the selected row moves past the visible terminal area, the list scrolls so the selector remains visible. Press Enter or `d` on an individual change to see its file, metadata query, modifier, detection time, and Git diff summary. Press Enter or `d` on a metadata type to open `TYPE DETAILS`, which lists the changed components for that type in recent-first order.
 
 Press `p` to pause/resume, `r` to refresh, `s` for Salesforce only, `v` for Vlocity only, `a` for all, and `q`, `x`, `ESC`, `CTRL+C`, or `exit` to quit.
 
-For Vlocity-enabled orgs, the default monitor scope runs `packExportAllDefault` without a job file:
+For Vlocity-enabled orgs, the default monitor scope runs `packExportAllDefault` with a temporary job file that includes `continueAfterError: true`:
 
 ```bash
 sf metadelta monitor run --org DEV --scope vlocity
@@ -403,7 +412,7 @@ sf metadelta monitor run --org DEV --scope salesforce
 > **Linked ESM note:** When `sf` prints `@nervill/metadelta is a linked ESM module and cannot be auto-transpiled`, always run `npm run build` before testing commands. If your CLI still does not resolve `sf metadelta task record`, use `sf metadelta:task:record` and relink the plugin. Task diagnostics are saved in `.metadelta/metadelta-task-orchestrator.json`. This is mandatory after local code changes; otherwise `sf` may run stale compiled `lib/` output.
 > **Task play hardening:** `sf metadelta task play` now includes automatic stabilizers for frontdoor/base URL separation, initial Setup popup recovery, popup rebinds, App Launcher fallbacks, dynamic Permission Set Assignment selectors, and Action Library scroll selection + Finish enablement checks in the temporary `.metadelta.*` test file.
 > **Salesforce CLI secrets workaround (v0.11.4):** `sf metadelta task record` and `sf metadelta task play` build Salesforce frontdoor URLs from the alias passed in `--org`. When they need the real `accessToken`, Metadelta now runs the required `sf org display --target-org <alias> --verbose --json` calls with `SF_TEMP_SHOW_SECRETS=true` in the child process environment. This keeps the automation compatible with Salesforce CLI outputs that redact secrets, without asking users to run `sf org auth ...` interactively or set the workaround globally.
-> **Monitor Vlocity support (v0.11.8):** `sf metadelta monitor run` can monitor Vlocity-only sessions with `--scope vlocity` and uses `vlocity -sfdx.username <orgAlias> --projectPath <paths.vlocity> -nojob packExportAllDefault`.
+> **Monitor Vlocity support (v0.11.9):** `sf metadelta monitor run` can monitor Vlocity-only sessions with `--scope vlocity` and uses `vlocity -sfdx.username <orgAlias> -job <temporary-yaml> --projectPath <paths.vlocity> packExportAllDefault`. The temporary YAML sets `continueAfterError: true`.
 > **Task orchestrator diagnostics:** The orchestrator now stores the most relevant Playwright failure excerpt (not only the exit code), making solution matching and future triage more accurate in `.metadelta/metadelta-task-orchestrator.json`.
 > **Report a task-play issue:** If playback fails, please open a public GitHub Issue at <https://github.com/NerioVillalobos/plugin-metadelta/issues> and include: (1) command executed, (2) full error text, (3) screenshot captured while running with `--header`, and (4) sanitized `.metadelta.*` snippet around the failing step.
 
@@ -1010,13 +1019,22 @@ Inicia un monitor temporal de terminal para detectar drift de metadatos Salesfor
 sf metadelta monitor run --org DEV
 ```
 
+Opciones:
+
+| Flag | Descripción | Valor por defecto |
+| --- | --- | --- |
+| `--org`, `-o` | Alias o username del org destino. | Requerido |
+| `--interval` | Intervalo de refresh en minutos. Los valores menores a `1` se normalizan a `1`. | `5` |
+| `--scope` | Fuente de metadata a monitorear: `all`, `salesforce` o `vlocity`. | `all` |
+| `--once` | Ejecuta un solo ciclo de refresh y sale después del cleanup. Útil para validación. | `false` |
+
 El monitor crea `.metadelta-monitor/`, recupera el snapshot actual de metadatos, inicializa un repositorio Git local como motor de diff y refresca cada cinco minutos. `NEXT` muestra la hora exacta del próximo refresh en vez de repintar un countdown. El primer ciclo crea la línea base y muestra `STATUS: BASELINE CREATED`; los siguientes refresh muestran archivos agregados, modificados, eliminados o renombrados. Los errores completos y avisos de Vlocity se muestran envueltos en una sección de detalle y pausan automáticamente el repintado de la UI para poder seleccionar/copiar el texto.
 
 La UI tiene dos secciones navegables. `SALESFORCE CORE / VLOCITY` agrupa cambios por tipo de metadata y muestra contador, fecha del último cambio y último usuario modificador para cada tipo. `RECENT CHANGES` lista los cambios acumulados de la sesión con los elementos detectados más recientemente primero. Las flechas mueven el selector `>` por ambas secciones; cuando la fila seleccionada supera el área visible de la terminal, la lista se desplaza para mantener el selector en pantalla. Presiona Enter o `d` sobre un cambio individual para ver archivo, query de metadata, modificador, hora de detección y resumen del diff Git. Presiona Enter o `d` sobre un tipo de metadata para abrir `TYPE DETAILS`, que lista los componentes cambiados de ese tipo en orden reciente primero.
 
 Presiona `p` para pausar/reanudar, `r` para refrescar, `s` para solo Salesforce, `v` para solo Vlocity, `a` para todo y `q`, `x`, `ESC`, `CTRL+C` o `exit` para salir.
 
-Para orgs con Vlocity habilitado, el scope por defecto del monitor ejecuta `packExportAllDefault` sin archivo job:
+Para orgs con Vlocity habilitado, el scope por defecto del monitor ejecuta `packExportAllDefault` con un job YAML temporal que incluye `continueAfterError: true`:
 
 ```bash
 sf metadelta monitor run --org DEV --scope vlocity
@@ -1033,7 +1051,7 @@ sf metadelta monitor run --org DEV --scope salesforce
 > **Nota para ESM enlazado:** Si `sf` muestra `@nervill/metadelta is a linked ESM module and cannot be auto-transpiled`, ejecuta `npm run build` antes de probar comandos. Si la CLI no resuelve `sf metadelta task record`, usa `sf metadelta:task:record` y vuelve a enlazar el plugin. El diagnóstico de tareas se guarda en `.metadelta/metadelta-task-orchestrator.json`. Esto es obligatorio tras cambios locales de código; de lo contrario `sf` puede ejecutar un `lib/` compilado desactualizado.
 > **Robustez en task play:** `sf metadelta task play` incluye estabilizadores automáticos para separar frontdoor/base URL, recuperar la apertura inicial del popup de Setup, reabrir popups, aplicar fallback en App Launcher, normalizar selectores dinámicos de Permission Set Assignment y resolver selección con scroll + validación de botón Finish en Action Library dentro del archivo temporal `.metadelta.*`.
 > **Workaround de secretos de Salesforce CLI (v0.11.4):** `sf metadelta task record` y `sf metadelta task play` construyen URLs frontdoor usando el alias recibido en `--org`. Cuando necesitan el `accessToken` real, Metadelta ejecuta las llamadas requeridas a `sf org display --target-org <alias> --verbose --json` con `SF_TEMP_SHOW_SECRETS=true` en el entorno del proceso hijo. Esto mantiene la automatización compatible con salidas de Salesforce CLI que ocultan secretos, sin pedir al usuario ejecutar `sf org auth ...` de forma interactiva ni configurar el workaround globalmente.
-> **Soporte monitor Vlocity (v0.11.8):** `sf metadelta monitor run` puede monitorear sesiones solo Vlocity con `--scope vlocity` y usa `vlocity -sfdx.username <orgAlias> --projectPath <paths.vlocity> -nojob packExportAllDefault`.
+> **Soporte monitor Vlocity (v0.11.9):** `sf metadelta monitor run` puede monitorear sesiones solo Vlocity con `--scope vlocity` y usa `vlocity -sfdx.username <orgAlias> -job <temporary-yaml> --projectPath <paths.vlocity> packExportAllDefault`. El YAML temporal define `continueAfterError: true`.
 > **Diagnóstico del orquestador:** El orquestador ahora guarda el fragmento más relevante del fallo de Playwright (no solo el código de salida), mejorando el match de soluciones y el triage futuro dentro de `.metadelta/metadelta-task-orchestrator.json`.
 > **Reportar incidencias de task play:** Si la reproducción falla, abre un Issue público en GitHub: <https://github.com/NerioVillalobos/plugin-metadelta/issues> e incluye: (1) comando ejecutado, (2) texto completo del error, (3) captura ejecutando con `--header`, y (4) fragmento saneado del archivo `.metadelta.*` en el paso donde falla.
 

lib/utils/monitor/retriever.js

@@ -32,17 +32,25 @@ export async function exportVlocity(paths, orgAlias, options = {}) {
         }
         return { skipped: true, reason };
     }
+    const jobPath = writeVlocityMonitorJob(paths);
     try {
-        await runProcess('vlocity', ['-sfdx.username', orgAlias, '--projectPath', paths.vlocity, '-nojob', 'packExportAllDefault'], { cwd: paths.orgRoot });
+        await runProcess('vlocity', ['-sfdx.username', orgAlias, '-job', jobPath, '--projectPath', paths.vlocity, 'packExportAllDefault'], { cwd: paths.orgRoot });
     }
     catch (error) {
         removeIgnoredMonitorFiles(paths.vlocity);
+        const hasExportedFiles = hasMonitorFiles(paths.vlocity);
         if (isSampleInputJsonError(error.message)) {
             return {
                 skipped: false,
                 warning: 'Vlocity export tuvo errores en *_SampleInputJson.json; esos archivos fueron ignorados por el monitor.',
             };
         }
+        if (hasExportedFiles) {
+            return {
+                skipped: false,
+                warning: `Vlocity export terminó con errores, pero se conservaron los DataPacks exportados parcialmente:\n${error.message}`,
+            };
+        }
         if (required) {
             throw error;
         }
@@ -54,6 +62,35 @@ export async function exportVlocity(paths, orgAlias, options = {}) {
     removeIgnoredMonitorFiles(paths.vlocity);
     return { skipped: false };
 }
+function writeVlocityMonitorJob(paths) {
+    fs.mkdirSync(paths.manifest, { recursive: true });
+    const jobPath = path.join(paths.manifest, 'monitor-vlocity-export.yaml');
+    const yaml = [
+        `projectPath: ${yamlScalar(paths.vlocity)}`,
+        'continueAfterError: true',
+        'compileOnBuild: false',
+        'maxDepth: 0',
+        'autoUpdateSettings: true',
+        '',
+        'OverrideSettings:',
+        '    DataPacks:',
+        '        Catalog:',
+        '        Product2:',
+        '            MaxDeploy: 1',
+        '',
+    ].join('\n');
+    fs.writeFileSync(jobPath, yaml, 'utf8');
+    return jobPath;
+}
+function yamlScalar(value) {
+    return `'${String(value).replace(/'/g, "''")}'`;
+}
+function hasMonitorFiles(root) {
+    if (!fs.existsSync(root)) {
+        return false;
+    }
+    return collectFiles(root).some((filePath) => !isIgnoredMonitorFile(filePath));
+}
 function removeIgnoredMonitorFiles(root) {
     if (!fs.existsSync(root)) {
         return;

oclif.manifest.json

@@ -915,5 +915,5 @@
       ]
     }
   },
-  "version": "0.11.8"
+  "version": "0.11.9"
 }

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@nervill/metadelta",
-  "version": "0.11.8",
+  "version": "0.11.9",
   "description": "Salesforce CLI plugin to find recent metadata changes in an org",
   "type": "module",
   "main": "lib/index.js",

package.json

@@ -40,20 +40,28 @@ export async function exportVlocity(paths, orgAlias, options = {}) {
     return {skipped: true, reason};
   }
 
+  const jobPath = writeVlocityMonitorJob(paths);
   try {
     await runProcess(
       'vlocity',
-      ['-sfdx.username', orgAlias, '--projectPath', paths.vlocity, '-nojob', 'packExportAllDefault'],
+      ['-sfdx.username', orgAlias, '-job', jobPath, '--projectPath', paths.vlocity, 'packExportAllDefault'],
       {cwd: paths.orgRoot}
     );
   } catch (error) {
     removeIgnoredMonitorFiles(paths.vlocity);
+    const hasExportedFiles = hasMonitorFiles(paths.vlocity);
     if (isSampleInputJsonError(error.message)) {
       return {
         skipped: false,
         warning: 'Vlocity export tuvo errores en *_SampleInputJson.json; esos archivos fueron ignorados por el monitor.',
       };
     }
+    if (hasExportedFiles) {
+      return {
+        skipped: false,
+        warning: `Vlocity export terminó con errores, pero se conservaron los DataPacks exportados parcialmente:\n${error.message}`,
+      };
+    }
     if (required) {
       throw error;
     }
@@ -66,6 +74,38 @@ export async function exportVlocity(paths, orgAlias, options = {}) {
   return {skipped: false};
 }
 
+function writeVlocityMonitorJob(paths) {
+  fs.mkdirSync(paths.manifest, {recursive: true});
+  const jobPath = path.join(paths.manifest, 'monitor-vlocity-export.yaml');
+  const yaml = [
+    `projectPath: ${yamlScalar(paths.vlocity)}`,
+    'continueAfterError: true',
+    'compileOnBuild: false',
+    'maxDepth: 0',
+    'autoUpdateSettings: true',
+    '',
+    'OverrideSettings:',
+    '    DataPacks:',
+    '        Catalog:',
+    '        Product2:',
+    '            MaxDeploy: 1',
+    '',
+  ].join('\n');
+  fs.writeFileSync(jobPath, yaml, 'utf8');
+  return jobPath;
+}
+
+function yamlScalar(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+function hasMonitorFiles(root) {
+  if (!fs.existsSync(root)) {
+    return false;
+  }
+  return collectFiles(root).some((filePath) => !isIgnoredMonitorFile(filePath));
+}
+
 function removeIgnoredMonitorFiles(root) {
   if (!fs.existsSync(root)) {
     return;