execonvert 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -9,6 +9,34 @@ Categorías usadas: **Añadido**, **Cambiado**, **Corregido**, **Eliminado**.
 
 ## [Unreleased]
 
+## [0.5.5] - 2026-09-05
+
+### Añadido
+- `execonvert inspect` muestra la versión de eXeLearning con la que se creó el
+  proyecto, y la incluye en su salida `--json` como `exeVersion`.
+- Aviso al convertir un `.elpx` creado con una versión de eXeLearning más
+  reciente que la que incorpora eXeConvert: la conversión sigue adelante, pero
+  puede no reconocer los elementos nuevos. Los proyectos de versiones iguales o
+  anteriores no muestran nada, porque funcionan.
+
+### Corregido
+- Los `.elpx` generados declaraban `exe_version` 3.0, un valor heredado de la
+  plantilla, cuando el runtime incorporado es el 4.0.3. Ahora declaran la
+  versión real, que es la que escribe eXeLearning en sus propios archivos. El
+  campo es informativo: nada en el runtime lo usa para tomar decisiones.
+
+## [0.5.4] - 2026-09-05
+
+### Corregido
+- Una opción mal escrita con un solo guion (por ejemplo `-o salida.elpx`) se
+  tomaba como si fuera un archivo de entrada y se descartaba sin decir nada,
+  mientras la conversión escribía en su destino por defecto. Si allí ya había un
+  archivo con ese nombre, se sobrescribía sin aviso. Ahora se rechaza como
+  opción desconocida. Para elegir la salida siguen estando
+  `execonvert <entrada> <salida>` y `--out-dir`.
+- Los archivos de entrada que se descartan por no admitir la conversión pedida
+  se anuncian por la salida de errores en lugar de desaparecer en silencio.
+
 ## [0.5.3] - 2026-09-05
 
 ### Corregido

package/dist/cli/cli/execonvert.js

@@ -3,16 +3,17 @@ import { globSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { stderr, stdout } from 'node:process';
 import { createI18n } from '../src/i18n.js';
-import { buildPrintableHtmlDocument, buildPdfBlobFromPrintableHtml, convertElpxToDocx, convertElpxToHtml, convertHtmlToDocxResult, inspectElpxPages, } from '../src/converter.js';
+import { buildPrintableHtmlDocument, buildPdfBlobFromPrintableHtml, convertElpxToDocx, convertElpxToHtml, convertHtmlToDocxResult, inspectElpx, inspectElpxPages, } from '../src/converter.js';
 import { convertDocxToElpx } from '../src/docx-import.js';
 import { convertElpxToMarkdown } from '../src/elpx-markdown.js';
 import { convertElpToElpx } from '../src/legacy-elp.js';
 import { convertMarkdownToElpx } from '../src/markdown-import.js';
 import { installCliRuntime } from './runtime.js';
+import { EXE_RUNTIME_VERSION, isNewerThanRuntime } from '../src/exe-runtime.js';
 import { automaticCheck, autoCheckAllowed, runUpdate, updateText } from './updates.js';
-const CLI_VERSION = '0.5.3'.startsWith('__')
+const CLI_VERSION = '0.5.5'.startsWith('__')
     ? String(JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version)
-    : '0.5.3';
+    : '0.5.5';
 const cliMessages = {
     es: {
         'help.title': 'CLI de eXeConvert',
@@ -31,6 +32,8 @@ const cliMessages = {
         'help.output.docx': 'desde .docx: .elpx',
         'help.output.markdown': 'desde .md/.txt: .elpx',
         'help.option.to': 'Formato de salida para conversión múltiple (elpx, docx, md, pdf). Los archivos no compatibles se ignoran.',
+        'warn.skippedInput': 'Aviso: se ignora {file}: no se puede convertir a {format}.',
+        'warn.newerProject': 'Aviso: el proyecto se creó con eXeLearning {version} y esta versión incorpora la {runtime}. La conversión puede no reconocer los elementos nuevos.',
         'help.option.outDir': 'Directorio de salida (por defecto: mismo directorio que cada entrada)',
         'help.option.json': 'Imprime JSON legible por máquina',
         'help.option.pages': 'Exporta solo las referencias de página seleccionadas de un .elpx',
@@ -79,6 +82,8 @@ const cliMessages = {
         'help.output.docx': 'des de .docx: .elpx',
         'help.output.markdown': 'des de .md/.txt: .elpx',
         'help.option.to': 'Format de sortida per a conversió múltiple (elpx, docx, md, pdf). Els fitxers no compatibles s’ignoren.',
+        'warn.skippedInput': 'Avís: s’ignora {file}: no es pot convertir a {format}.',
+        'warn.newerProject': 'Avís: el projecte s’ha creat amb eXeLearning {version} i aquesta versió incorpora la {runtime}. La conversió pot no reconèixer els elements nous.',
         'help.option.outDir': 'Directori de sortida (per defecte: mateix directori que cada entrada)',
         'help.option.json': 'Imprimeix JSON llegible per màquines',
         'help.option.pages': 'Exporta només les referències de pàgina seleccionades d’un .elpx',
@@ -127,6 +132,8 @@ const cliMessages = {
         'help.output.docx': 'from .docx: .elpx',
         'help.output.markdown': 'from .md/.txt: .elpx',
         'help.option.to': 'Output format for batch conversion (elpx, docx, md, pdf). Incompatible files are skipped.',
+        'warn.skippedInput': 'Warning: skipping {file}: it cannot be converted to {format}.',
+        'warn.newerProject': 'Warning: this project was created with eXeLearning {version} and this build carries {runtime}. The conversion may not recognise its newer elements.',
         'help.option.outDir': 'Output directory (default: same directory as each input)',
         'help.option.json': 'Print machine-readable JSON',
         'help.option.pages': 'Export only selected page refs from an .elpx input',
@@ -343,6 +350,12 @@ function parseOptionFlags(args, defaults, t) {
     for (let index = 0; index < args.length; index += 1) {
         const value = args[index];
         if (!value.startsWith('--')) {
+            // A single dash is a mistyped option, not a file: taking it as one made
+            // "-o out.elpx" silently convert to the default destination instead,
+            // which can overwrite an existing file next to the input.
+            if (value.length > 1 && value.startsWith('-')) {
+                throw new Error(t('error.unknownOption', { value }));
+            }
             positionals.push(value);
             continue;
         }
@@ -539,11 +552,15 @@ function printInspectText(pages) {
 async function runInspect(inputPath, json) {
     installCliRuntime();
     const inputFile = await readInputFile(inputPath, buildMime('elpx'));
-    const pages = buildPageRefs(await inspectElpxPages(inputFile));
+    const inspection = await inspectElpx(inputFile);
+    const pages = buildPageRefs(inspection.pages);
     if (json) {
-        stdout.write(`${JSON.stringify({ input: resolve(inputPath), pages }, null, 2)}\n`);
+        stdout.write(`${JSON.stringify({ input: resolve(inputPath), exeVersion: inspection.exeVersion, pages }, null, 2)}\n`);
         return;
     }
+    if (inspection.exeVersion) {
+        stdout.write(`eXeLearning: ${inspection.exeVersion}\n`);
+    }
     printInspectText(pages);
 }
 async function runConvert(args) {
@@ -554,6 +571,9 @@ async function runConvert(args) {
     const inputFormat = detectFormat(inputPath, i18n.t);
     const outputFormat = detectFormat(outputPath, i18n.t);
     const inputFile = await readInputFile(inputPath, buildMime(inputFormat));
+    if (inputFormat === 'elpx' && !args.json) {
+        await warnIfNewerThanRuntime(inputFile, i18n.t);
+    }
     const selectedPageIds = inputFormat === 'elpx'
         ? await loadSelectedPageIds(inputFile, args.pages, args.pageIds)
         : [];
@@ -704,6 +724,21 @@ async function runConvert(args) {
     }
     throw new Error(i18n.t('error.unsupportedConversion', { input: inputFormat, output: outputFormat }));
 }
+// Only newer projects are worth a warning: older ones convert fine, as every
+// release from 4.0.0 on has shown. A project from a release this build does not
+// know may carry elements the conversion drops without saying anything.
+async function warnIfNewerThanRuntime(inputFile, t) {
+    try {
+        const { exeVersion } = await inspectElpx(inputFile);
+        if (isNewerThanRuntime(exeVersion)) {
+            stderr.write(`${t('warn.newerProject', { version: exeVersion, runtime: EXE_RUNTIME_VERSION })}\n`);
+        }
+    }
+    catch {
+        // Inspecting is only for the warning: a project that cannot be read here
+        // will fail with its own message further down.
+    }
+}
 async function loadSelectedPageIds(inputFile, pageRefs, pageIds) {
     if (pageRefs.length === 0 && pageIds.length === 0) {
         return [];
@@ -767,6 +802,16 @@ async function runBatch(args) {
             return false;
         }
     });
+    // Skipping is deliberate for globs like "*.docx --to pdf", but doing it in
+    // silence hides typos: an unknown option taken as a filename disappeared
+    // without a word while the conversion wrote to its default destination.
+    if (!args.json) {
+        for (const inputPath of inputPaths) {
+            if (!eligible.includes(inputPath)) {
+                stderr.write(i18n.t('warn.skippedInput', { file: basename(inputPath), format: toRaw }) + '\n');
+            }
+        }
+    }
     let count = 0;
     for (const inputPath of eligible) {
         if (!args.json) {

package/dist/cli/src/converter.js

@@ -1830,15 +1830,26 @@ function ensurePdfMakeFonts() {
     pdfMakeInitialized = true;
 }
 export async function inspectElpxPages(file) {
+    return (await inspectElpx(file)).pages;
+}
+/**
+ * Reads the pages and the eXeLearning release the project declares. The version
+ * is what tells a caller whether the project comes from a release newer than the
+ * vendored runtime, in which case the conversion may not know every element.
+ */
+export async function inspectElpx(file) {
     const input = new Uint8Array(await file.arrayBuffer());
     const entries = unzipSync(input);
     const project = parseProject(entries);
-    return project.pages.map(page => ({
-        id: page.id,
-        parentId: page.parentId,
-        title: page.title,
-        depth: page.depth,
-    }));
+    return {
+        exeVersion: project.exeVersion,
+        pages: project.pages.map(page => ({
+            id: page.id,
+            parentId: page.parentId,
+            title: page.title,
+            depth: page.depth,
+        })),
+    };
 }
 async function buildCompatibleDocx(htmlDocument) {
     const htmlDoc = new DOMParser().parseFromString(htmlDocument, 'text/html');
@@ -1958,6 +1969,7 @@ function parseProject(entries) {
     if (parserError) {
         throw new Error('El content.xml no se ha podido interpretar correctamente.');
     }
+    const exeVersion = findResourceValue(xmlDoc, 'exe_version');
     const title = findPropertyValue(xmlDoc, 'pp_title') || 'eXeLearning';
     const subtitle = findPropertyValue(xmlDoc, 'pp_subtitle') || '';
     const language = findPropertyValue(xmlDoc, 'pp_lang') || 'es';
@@ -1969,6 +1981,7 @@ function parseProject(entries) {
         title,
         subtitle,
         language,
+        exeVersion,
         pages: sortPagesHierarchically(pages),
     };
 }
@@ -4953,6 +4966,17 @@ function toDocxHeadingLevel(level) {
             return HeadingLevel.HEADING_6;
     }
 }
+// eXeLearning records the release that wrote the project as an odeResource.
+// It is descriptive only -- nothing in the runtime reads it to decide anything.
+function findResourceValue(xmlDoc, key) {
+    const nodes = Array.from(xmlDoc.getElementsByTagName('odeResource'));
+    for (const node of nodes) {
+        if (getDirectText(node, 'key') === key) {
+            return getDirectText(node, 'value');
+        }
+    }
+    return null;
+}
 function findPropertyValue(xmlDoc, key) {
     const nodes = Array.from(xmlDoc.getElementsByTagName('odeProperty'));
     for (const node of nodes) {

package/dist/cli/src/docx-import.js

@@ -2,6 +2,7 @@ import { unzipSync, zipSync } from 'fflate';
 import mammoth from 'mammoth';
 import { MathMLToLaTeX } from 'mathml-to-latex';
 import { DOMParser as XmldomParser, XMLSerializer as XmldomSerializer } from '@xmldom/xmldom';
+import { EXE_RUNTIME_VERSION } from './exe-runtime.js';
 // @ts-expect-error the vendored omml2mathml ships no TypeScript declarations.
 import omml2mathml from './vendor/omml2mathml/index.js';
 import temml from 'temml';
@@ -636,7 +637,7 @@ function generateContentXml(project) {
 <odeResources>
   <odeResource><key>odeId</key><value>${escapeXml(odeId)}</value></odeResource>
   <odeResource><key>odeVersionId</key><value>${escapeXml(odeVersionId)}</value></odeResource>
-  <odeResource><key>exe_version</key><value>3.0</value></odeResource>
+  <odeResource><key>exe_version</key><value>${EXE_RUNTIME_VERSION}</value></odeResource>
 </odeResources>
 <odeProperties>
   <odeProperty><key>pp_title</key><value>${escapeXml(project.title || 'Documento importado')}</value></odeProperty>

package/dist/cli/src/exe-runtime.js

@@ -0,0 +1,29 @@
+// The eXeLearning release whose runtime is vendored in this repository, kept in
+// step with app/public/exelearning/runtime-source.json by
+// tests/runtime-version.test.mjs, which npm run sync:exe updates.
+export const EXE_RUNTIME_VERSION = '4.0.3';
+/**
+ * Compares two eXeLearning versions. Returns true when `version` is newer than
+ * the vendored runtime, which is the only case worth warning about: a project
+ * from an older release converts fine, one from a newer release may carry
+ * elements this code does not know about and would drop without saying so.
+ */
+export function isNewerThanRuntime(version) {
+    if (!version) {
+        return false;
+    }
+    const parse = (value) => value.trim().replace(/^v/, '').split('.').map(part => Number.parseInt(part, 10));
+    const candidate = parse(version);
+    const runtime = parse(EXE_RUNTIME_VERSION);
+    if (candidate.some(Number.isNaN)) {
+        return false;
+    }
+    for (let index = 0; index < Math.max(candidate.length, runtime.length); index += 1) {
+        const left = candidate[index] ?? 0;
+        const right = runtime[index] ?? 0;
+        if (left !== right) {
+            return left > right;
+        }
+    }
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "execonvert",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "private": false,
   "repository": {
     "type": "git",
@@ -39,7 +39,9 @@
     "test:updates": "node --import tsx --test tests/updates.test.ts",
     "test:runtime": "node scripts/test-runtime.mjs",
     "test:cli": "node --test tests/cli-update.test.mjs",
-    "test:docx": "node --test tests/docx-omml.test.mjs"
+    "test:docx": "node --test tests/docx-omml.test.mjs",
+    "test:args": "node --test tests/cli-args.test.mjs",
+    "test:version": "node --import tsx --test tests/runtime-version.test.mjs"
   },
   "dependencies": {
     "@resvg/resvg-js": "^2.6.2",