execonvert 0.4.1 → 0.5.0

package/dist/cli/app/public/exelearning/runtime-source.json

@@ -1,10 +1,10 @@
 {
   "sourceRepo": "https://github.com/exelearning/exelearning",
   "sourceMode": "release",
-  "sourceReleaseTag": "v4.0.1",
-  "sourceReleaseAsset": "exelearning-static-v4.0.1.zip",
-  "sourceReleasePublishedAt": "2026-06-09T09:20:07Z",
-  "sourceCommit": "91d855aa799313aa77fc1f07771eb85ea17ccf94",
-  "sourceVersion": "4.0.1",
-  "syncedAt": "2026-06-25T06:16:41Z"
+  "sourceReleaseTag": "v4.0.3",
+  "sourceReleaseAsset": "exelearning-static-v4.0.3.zip",
+  "sourceReleasePublishedAt": "2026-08-06T11:24:07Z",
+  "sourceCommit": "3c7c7e82163e812f04cbb033240942f8ac1214a0",
+  "sourceVersion": "4.0.3",
+  "syncedAt": "2026-09-05T05:49:44Z"
 }

package/dist/cli/app/public/info/cli.html

@@ -133,6 +133,61 @@
         flex-wrap: wrap;
         gap: 12px;
         margin-top: 18px;
+        align-items: center;
+      }
+
+      .npm-install-inline {
+        display: flex;
+        align-items: center;
+        gap: 10px;
+        flex-wrap: wrap;
+      }
+
+      .npm-or {
+        color: var(--muted);
+        font-size: 0.98rem;
+        white-space: nowrap;
+      }
+
+      .npm-cmd-wrap {
+        display: inline-flex;
+        align-items: center;
+        gap: 0;
+        border-radius: 999px;
+        border: 1.5px solid var(--line);
+        background: #182117;
+        overflow: hidden;
+        height: 48px;
+      }
+
+      .npm-cmd {
+        padding: 0 14px 0 18px;
+        color: #eef7eb;
+        font-size: 0.92rem;
+        white-space: nowrap;
+        line-height: 1;
+      }
+
+      .copy-btn {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        height: 100%;
+        padding: 0 14px;
+        background: rgba(255,255,255,0.08);
+        border: none;
+        border-left: 1px solid rgba(255,255,255,0.12);
+        color: #a8d890;
+        font-family: inherit;
+        font-size: 0.85rem;
+        font-weight: 700;
+        cursor: pointer;
+        white-space: nowrap;
+        transition: background 0.15s;
+      }
+
+      .copy-btn:hover {
+        background: rgba(255,255,255,0.16);
       }
 
       .button {
@@ -356,6 +411,13 @@
 
         <div class="cta-row">
           <a id="cli-download-button" class="button primary" href="https://github.com/eXeConvert/eXeConvert.github.io/releases/latest" target="_blank" rel="noopener">Descargar la última versión</a>
+          <div class="npm-install-inline">
+            <span id="npm-or-label" class="npm-or">o con Node.js:</span>
+            <div class="npm-cmd-wrap">
+              <code id="npm-cmd-text" class="npm-cmd">npm install -g execonvert</code>
+              <button id="npm-copy-btn" class="copy-btn">Copiar</button>
+            </div>
+          </div>
         </div>
 
       </section>
@@ -517,6 +579,9 @@ execonvert inspect proyecto.elpx</pre>
           intro:
             "eXeConvert convierte archivos entre los formatos de eXeLearning (<code>.elpx</code>, <code>.elp</code>), Word (<code>.docx</code>), PDF y Markdown (<code>.md</code>). Esta es la versión de terminal o consola. Se usa desde una ventana de Terminal, PowerShell o cmd y es útil para convertir muchos archivos o automatizar tareas (si prefieres una interfaz gráfica, puedes usar <a href=\"../index.html\">la versión web de eXeConvert</a>).",
           downloadButton: "Descargar la última versión",
+          npmOrLabel: "o con Node.js:",
+          npmCopyBtn: "Copiar",
+          npmCopied: "Copiado",
           downloadsTitle: "Qué descargar",
           debTitle: "Ubuntu y otros sistemas basados en Debian",
           debText: "Descarga el paquete <code>.deb</code> desde la última release y ábrelo con el instalador del sistema.",
@@ -526,6 +591,8 @@ execonvert inspect proyecto.elpx</pre>
           windowsText: "Descarga el instalador <code>.exe</code> y sigue el asistente.",
           macosTitle: "macOS",
           macosText: "Descarga el instalador <code>.pkg</code> y sigue el proceso habitual de instalación.",
+          npmTitle: "Con Node.js (todas las plataformas)",
+          npmText: "Si tienes Node.js 22 o superior, instala con <code>npm install -g execonvert</code> o úsalo sin instalarlo con <code>npx execonvert</code>. Funciona en Linux, macOS y Windows.",
           note:
             "<strong>Importante:</strong> la CLI está pensada para terminal. Si prefieres trabajar con una interfaz gráfica, usa <a href=\"../index.html\">la página principal de eXeConvert</a>.",
           firstUseTitle: "Primer uso",
@@ -583,6 +650,9 @@ execonvert inspect proyecto.elpx</pre>
           intro:
             "eXeConvert converteix fitxers entre els formats d'eXeLearning (<code>.elpx</code>, <code>.elp</code>), Word (<code>.docx</code>), PDF i Markdown (<code>.md</code>). Aquesta és la versió de terminal o consola. Es fa servir des d'una finestra de Terminal, PowerShell o cmd i és útil per convertir molts fitxers o automatitzar tasques (si prefereixes una interfície gràfica, pots fer servir <a href=\"../index.html\">la versió web d'eXeConvert</a>).",
           downloadButton: "Descarregar l'última versió",
+          npmOrLabel: "o amb Node.js:",
+          npmCopyBtn: "Copiar",
+          npmCopied: "Copiat",
           downloadsTitle: "Què descarregar",
           debTitle: "Ubuntu i altres sistemes basats en Debian",
           debText: "Descarrega el paquet <code>.deb</code> des de l'última release i obre'l amb l'instal·lador del sistema.",
@@ -592,6 +662,8 @@ execonvert inspect proyecto.elpx</pre>
           windowsText: "Descarrega l'instal·lador <code>.exe</code> i segueix l'assistent.",
           macosTitle: "macOS",
           macosText: "Descarrega l'instal·lador <code>.pkg</code> i segueix el procés habitual d'instal·lació.",
+          npmTitle: "Amb Node.js (totes les plataformes)",
+          npmText: "Si tens Node.js 22 o superior, instal·la amb <code>npm install -g execonvert</code> o utilitza'l sense instal·lar amb <code>npx execonvert</code>. Funciona a Linux, macOS i Windows.",
           note:
             "<strong>Important:</strong> la CLI està pensada per al terminal. Si prefereixes treballar amb una interfície gràfica, fes servir <a href=\"../index.html\">la pàgina principal d'eXeConvert</a>.",
           firstUseTitle: "Primer ús",
@@ -649,6 +721,9 @@ execonvert inspect proyecto.elpx</pre>
           intro:
             "eXeConvert converts files between eXeLearning formats (<code>.elpx</code>, <code>.elp</code>), Word (<code>.docx</code>), PDF, and Markdown (<code>.md</code>). This is the terminal or console version. It is used from a Terminal, PowerShell, or cmd window and is useful for converting many files or automating tasks (if you prefer a graphical interface, you can use <a href=\"../index.html\">the web version of eXeConvert</a>).",
           downloadButton: "Download the latest version",
+          npmOrLabel: "or with Node.js:",
+          npmCopyBtn: "Copy",
+          npmCopied: "Copied",
           downloadsTitle: "What to download",
           debTitle: "Ubuntu and other Debian-based systems",
           debText: "Download the <code>.deb</code> package from the latest release and open it with the system installer.",
@@ -658,6 +733,8 @@ execonvert inspect proyecto.elpx</pre>
           windowsText: "Download the <code>.exe</code> installer and follow the setup wizard.",
           macosTitle: "macOS",
           macosText: "Download the <code>.pkg</code> installer and follow the usual installation process.",
+          npmTitle: "With Node.js (all platforms)",
+          npmText: "If you have Node.js 22 or higher, install with <code>npm install -g execonvert</code> or run without installing with <code>npx execonvert</code>. Works on Linux, macOS, and Windows.",
           note:
             "<strong>Important:</strong> the CLI is intended for terminal use. If you prefer a graphical interface, use <a href=\"../index.html\">the main eXeConvert page</a>.",
           firstUseTitle: "First steps",
@@ -756,6 +833,8 @@ execonvert inspect proyecto.elpx</pre>
         setText("cli-subtitle", copy.subtitle);
         setHtml("cli-intro", copy.intro);
         setText("cli-download-button", copy.downloadButton);
+        setText("npm-or-label", copy.npmOrLabel);
+        setText("npm-copy-btn", copy.npmCopyBtn);
         setText("downloads-title", copy.downloadsTitle);
         setText("download-deb-title", copy.debTitle);
         setHtml("download-deb-text", copy.debText);
@@ -914,17 +993,21 @@ execonvert inspect proyecto.elpx</pre>
       }
 
       function scheduleAnalyticsLoad() {
-        if ("requestIdleCallback" in window) {
-          window.requestIdleCallback(loadAnalyticsInBackground, { timeout: 2000 });
-          return;
-        }
-        const run = () => {
-          window.setTimeout(loadAnalyticsInBackground, 0);
+        // Un <script async> inyectado antes de que se dispare «load» retrasa ese
+        // evento hasta que la peticion termina. Si el servidor de estadisticas se
+        // cuelga, «load» no llegaria a dispararse nunca. Por eso se espera siempre
+        // a «load» antes de programar nada.
+        const programar = () => {
+          if ("requestIdleCallback" in window) {
+            window.requestIdleCallback(loadAnalyticsInBackground, { timeout: 2000 });
+          } else {
+            window.setTimeout(loadAnalyticsInBackground, 0);
+          }
         };
         if (document.readyState === "complete") {
-          run();
+          programar();
         } else {
-          window.addEventListener("load", run, { once: true });
+          window.addEventListener("load", programar, { once: true });
         }
       }
 
@@ -942,6 +1025,20 @@ execonvert inspect proyecto.elpx</pre>
         applyTranslations(locale);
       });
 
+      document.getElementById("npm-copy-btn")?.addEventListener("click", () => {
+        const cmd = document.getElementById("npm-cmd-text")?.textContent || "npm install -g execonvert";
+        navigator.clipboard.writeText(cmd).then(() => {
+          const btn = document.getElementById("npm-copy-btn");
+          const locale = document.documentElement.lang || activeLocale;
+          const copy = translations[locale] || translations.es;
+          const original = copy.npmCopyBtn;
+          if (btn) {
+            btn.textContent = copy.npmCopied;
+            setTimeout(() => { btn.textContent = original; }, 2000);
+          }
+        });
+      });
+
       document.getElementById("footer-privacy-link")?.addEventListener("click", event => {
         event.preventDefault();
         const privacy = document.getElementById("footer-privacy");

package/dist/cli/cli/execonvert.js

@@ -9,7 +9,10 @@ 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';
-const CLI_VERSION = '0.4.0';
+import { automaticCheck, autoCheckAllowed, runUpdate, updateText } from './updates.js';
+const CLI_VERSION = '0.5.0'.startsWith('__')
+    ? String(JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version)
+    : '0.5.0';
 const cliMessages = {
     es: {
         'help.title': 'CLI de eXeConvert',
@@ -216,6 +219,7 @@ ${t('help.usage')}:
   execonvert <input> <output> [options]
   execonvert <input1> [input2 ...] --to <format> [--out-dir <dir>] [options]
   execonvert inspect <input> [--json]
+  execonvert update [--check] [--json] [--out-dir <dir>]
 
 ${t('help.inputs')}:
   ${t('help.input.elp')}
@@ -244,6 +248,8 @@ ${t('help.options')}:
   --lang <code>           ${t('help.option.lang')}
   --help                  ${t('help.option.help')}
   --version               ${t('help.option.version')}
+  update [--check]         ${updateText(currentCliTranslator.locale, 'help')}
+  --no-update-check       ${updateText(currentCliTranslator.locale, 'disable')}
 
 ${t('help.examples')}:
   execonvert notes.md notes.elpx --h1 resource-title --h2 subpage --h3 idevice
@@ -260,6 +266,8 @@ function parseArgs(argv, t, locale) {
         locale,
         json: false,
         includeImages: false,
+        noUpdateCheck: false,
+        checkUpdate: false,
         h1: 'page',
         h2: 'idevice',
         h3: 'idevice',
@@ -274,6 +282,14 @@ function parseArgs(argv, t, locale) {
     if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
         return { ...defaults, command: 'help' };
     }
+    if (args[0] === 'update') {
+        args.shift();
+        const updateDefaults = { ...defaults, command: 'update' };
+        const parsed = parseOptionFlags(args, updateDefaults, t);
+        if (parsed.positionals.length)
+            throw new Error('Usage: execonvert update [--check] [--json] [--out-dir <dir>]');
+        return { ...updateDefaults, ...parsed.options };
+    }
     if (args[0] === 'inspect') {
         args.shift();
         const parsed = parseOptionFlags(args, defaults, t);
@@ -330,8 +346,19 @@ function parseOptionFlags(args, defaults, t) {
             positionals.push(value);
             continue;
         }
+        if (defaults.command === 'update' && !['--check', '--json', '--out-dir', '--lang', '--locale'].includes(value)) {
+            throw new Error(t('error.unknownOption', { value }));
+        }
         const nextValue = args[index + 1];
         switch (value) {
+            case '--no-update-check':
+                options.noUpdateCheck = true;
+                break;
+            case '--check':
+                if (defaults.command !== 'update')
+                    throw new Error(t('error.unknownOption', { value }));
+                options.checkUpdate = true;
+                break;
             case '--lang':
             case '--locale':
                 ensureOptionValue(value, nextValue, t);
@@ -790,15 +817,28 @@ async function main() {
         stdout.write(`${CLI_VERSION}\n`);
         return;
     }
-    if (args.command === 'inspect') {
-        await runInspect(args.inputPath, args.json);
+    if (args.command === 'update') {
+        await runUpdate({ current: CLI_VERSION, locale, check: args.checkUpdate, json: args.json, outDir: args.outDir });
         return;
     }
-    if (args.command === 'batch') {
-        await runBatch(args);
-        return;
+    const updateController = new AbortController();
+    if (autoCheckAllowed({ ...args, disabled: args.noUpdateCheck })) {
+        void automaticCheck(CLI_VERSION, locale, updateController.signal);
+    }
+    try {
+        if (args.command === 'inspect') {
+            await runInspect(args.inputPath, args.json);
+            return;
+        }
+        if (args.command === 'batch') {
+            await runBatch(args);
+            return;
+        }
+        await runConvert(args);
+    }
+    finally {
+        updateController.abort();
     }
-    await runConvert(args);
 }
 await main().catch(error => {
     const message = error instanceof Error ? error.message : String(error);

package/dist/cli/cli/updates.js

@@ -0,0 +1,315 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { chmod, mkdir, open, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const RELEASE_REPO = 'eXeConvert/eXeConvert.github.io';
+const RELEASE_URL = `https://github.com/${RELEASE_REPO}/releases`;
+const DAY = 24 * 60 * 60 * 1000;
+const nativeFetch = globalThis.fetch.bind(globalThis);
+const messages = {
+    es: {
+        available: 'Hay una actualización de eXeConvert: {current} → {latest}. Ejecuta execonvert update.',
+        current: 'eXeConvert {current} está actualizado (última versión estable: {latest}).',
+        downloaded: 'Descargado y verificado: {path}',
+        installed: 'eXeConvert {latest} instalado mediante npm.',
+        source: 'Esta copia es un repositorio de desarrollo. Actualízala mediante Git y recompílala. Versiones publicadas: {url}',
+        unknown: 'No se reconoce el tipo de instalación. Descarga el paquete adecuado desde {url}',
+        apply: 'Instala el archivo descargado con el instalador del sistema. La instalación actual sigue disponible.',
+        appimage: 'Da permiso de ejecución al archivo descargado y úsalo en lugar del AppImage anterior.',
+        missing: 'La versión {latest} aún no tiene un paquete para {kind}/{platform}/{arch}. Consulta {url}',
+        network: 'No se han podido comprobar las actualizaciones: {message}',
+        help: 'Comprueba o descarga actualizaciones de eXeConvert',
+        disable: 'Desactiva la comprobación automática de actualizaciones',
+    },
+    ca: {
+        available: 'Hi ha una actualització d’eXeConvert: {current} → {latest}. Executa execonvert update.',
+        current: 'eXeConvert {current} està actualitzat (darrera versió estable: {latest}).',
+        downloaded: 'Descarregat i verificat: {path}',
+        installed: 'eXeConvert {latest} instal·lat mitjançant npm.',
+        source: 'Aquesta còpia és un repositori de desenvolupament. Actualitza-la amb Git i recompila-la. Versions publicades: {url}',
+        unknown: 'No es reconeix el tipus d’instal·lació. Descarrega el paquet adequat des de {url}',
+        apply: 'Instal·la el fitxer descarregat amb l’instal·lador del sistema. La instal·lació actual continua disponible.',
+        appimage: 'Dona permís d’execució al fitxer descarregat i fes-lo servir en lloc de l’AppImage anterior.',
+        missing: 'La versió {latest} encara no té cap paquet per a {kind}/{platform}/{arch}. Consulta {url}',
+        network: 'No s’han pogut comprovar les actualitzacions: {message}',
+        help: 'Comprova o descarrega actualitzacions d’eXeConvert',
+        disable: 'Desactiva la comprovació automàtica d’actualitzacions',
+    },
+    en: {
+        available: 'eXeConvert update available: {current} → {latest}. Run execonvert update.',
+        current: 'eXeConvert {current} is up to date (latest stable: {latest}).',
+        downloaded: 'Downloaded and verified: {path}',
+        installed: 'eXeConvert {latest} installed using npm.',
+        source: 'This is a development checkout. Update it using Git and rebuild. Published releases: {url}',
+        unknown: 'Unrecognized installation type. Download the appropriate package from {url}',
+        apply: 'Install the downloaded file using the system installer. Your current installation remains available.',
+        appimage: 'Make the downloaded file executable and use it in place of the previous AppImage.',
+        missing: 'Release {latest} does not have a package for {kind}/{platform}/{arch} yet. See {url}',
+        network: 'Could not check for updates: {message}',
+        help: 'Check for or download eXeConvert updates',
+        disable: 'Disable automatic update checks',
+    },
+};
+export function updateText(locale, key, vars = {}) {
+    return messages[locale][key].replace(/\{(\w+)\}/g, (_, name) => vars[name] ?? `{${name}}`);
+}
+// Release tags must be stable SemVer; never install prereleases or compare lexically.
+export function stableVersion(value) {
+    const match = /^v?((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*))(?:\+[\w.-]+)?$/.exec(value);
+    if (!match)
+        throw new Error(`Invalid stable version: ${value}`);
+    return match[1];
+}
+export function isNewer(latest, current) {
+    const a = stableVersion(latest).split('.').map(BigInt);
+    const b = stableVersion(current).split('.').map(BigInt);
+    for (let i = 0; i < 3; i++)
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    return false;
+}
+export function packageRoot() {
+    const dir = dirname(fileURLToPath(import.meta.url));
+    return basename(dirname(dir)) === 'cli' && basename(dirname(dirname(dir))) === 'dist'
+        ? resolve(dir, '../../..') : resolve(dir, '..');
+}
+export async function detectInstallation(root = packageRoot(), env = process.env) {
+    const base = { root, platform: process.platform, arch: process.arch };
+    if (existsSync(join(root, 'scripts/build-cli.mjs')))
+        return { ...base, kind: 'source' };
+    try {
+        const marker = JSON.parse(await readFile(join(root, 'install-channel.json'), 'utf8'));
+        if (['deb', 'appimage', 'pkg', 'windows'].includes(marker.kind) &&
+            marker.platform === process.platform && marker.arch === process.arch)
+            return { ...base, kind: marker.kind };
+    }
+    catch { /* Older packages did not include a marker. */ }
+    if (env.EXECONVERT_RUNTIME_ROOT) {
+        if (env.APPIMAGE && process.platform === 'linux')
+            return { ...base, kind: 'appimage' };
+        if (process.platform === 'linux' && root === '/opt/execonvert')
+            return { ...base, kind: 'deb' };
+        if (process.platform === 'darwin' && root === '/usr/local/lib/execonvert')
+            return { ...base, kind: 'pkg' };
+        if (process.platform === 'win32')
+            return { ...base, kind: 'windows' };
+    }
+    if (basename(dirname(root)) === 'node_modules')
+        return { ...base, kind: 'npm' };
+    return { ...base, kind: 'unknown' };
+}
+export function validateRelease(data) {
+    if (!data || data.draft || data.prerelease || !Array.isArray(data.assets))
+        throw new Error('Invalid stable release response');
+    stableVersion(data.tag_name);
+    if (data.html_url !== `${RELEASE_URL}/tag/${data.tag_name}`)
+        throw new Error('Unexpected release URL');
+    return data;
+}
+export async function latestRelease(fetcher = nativeFetch, signal) {
+    const response = await fetcher(`https://api.github.com/repos/${RELEASE_REPO}/releases/latest`, {
+        headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'execonvert-update', 'X-GitHub-Api-Version': '2022-11-28' },
+        signal: signal ?? AbortSignal.timeout(10000),
+    });
+    if (!response.ok)
+        throw new Error(`GitHub HTTP ${response.status}`);
+    return validateRelease(await response.json());
+}
+export function selectAsset(release, install) {
+    const version = stableVersion(release.tag_name);
+    const { kind, platform, arch } = install;
+    let name;
+    if (kind === 'npm')
+        name = `execonvert-${version}.tgz`;
+    if (kind === 'deb' && platform === 'linux' && arch === 'x64')
+        name = `execonvert_${version}_amd64.deb`;
+    if (kind === 'appimage' && platform === 'linux' && arch === 'x64')
+        name = `execonvert-${version}-x86_64.AppImage`;
+    if (kind === 'pkg' && platform === 'darwin')
+        name = `execonvert-${version}-${arch}.pkg`;
+    if (kind === 'windows' && platform === 'win32')
+        name = `execonvert-${version}-${arch}-setup.exe`;
+    // Old Windows releases were built on x64. Old macOS assets do not identify
+    // their architecture, so do not guess which processor they support.
+    if (kind === 'windows' && arch === 'x64' && !release.assets.some(a => a.name === name))
+        name = `execonvert-${version}-setup.exe`;
+    return release.assets.find(asset => asset.name === name);
+}
+export function updateCacheDir(env = process.env, platform = process.platform) {
+    const base = platform === 'win32' ? (env.LOCALAPPDATA || join(homedir(), 'AppData/Local'))
+        : platform === 'darwin' ? join(homedir(), 'Library/Caches') : (env.XDG_CACHE_HOME || join(homedir(), '.cache'));
+    return join(base, 'execonvert');
+}
+export function autoCheckAllowed(options, env = process.env, interactive = Boolean(process.stdout.isTTY && process.stderr.isTTY)) {
+    return interactive && !options.json && !options.disabled && !env.CI && env.EXECONVERT_NO_UPDATE_CHECK !== '1' &&
+        !['help', 'version', 'update'].includes(options.command);
+}
+// The caller aborts on completion: checking cannot hold up a conversion's exit.
+// A lock serializes concurrent CLI launches. Failed requests are throttled too.
+export async function automaticCheck(current, locale, signal, options = {}) {
+    const cacheDir = options.cacheDir ?? updateCacheDir();
+    const lock = join(cacheDir, 'update-check.lock');
+    let ownsLock = false;
+    try {
+        if (signal.aborted)
+            return;
+        const now = options.now ?? Date.now();
+        await mkdir(cacheDir, { recursive: true });
+        // An expired lock can only belong to a crashed process: requests last <= 3s.
+        try {
+            if (Date.now() - (await stat(lock)).mtimeMs > DAY)
+                await rm(lock, { force: true });
+        }
+        catch { /* No lock. */ }
+        const handle = await open(lock, 'wx');
+        ownsLock = true;
+        try {
+            await handle.writeFile(String(now));
+        }
+        finally {
+            await handle.close();
+        }
+        const statePath = join(cacheDir, 'update-check.json');
+        try {
+            const state = JSON.parse(await readFile(statePath, 'utf8'));
+            if (Number.isFinite(state.checkedAt) && now >= state.checkedAt && now - state.checkedAt < DAY)
+                return;
+        }
+        catch { /* Missing or corrupt cache. */ }
+        if (signal.aborted)
+            return;
+        await writeFile(statePath, JSON.stringify({ checkedAt: now }));
+        const release = await latestRelease(options.fetcher, AbortSignal.any([signal, AbortSignal.timeout(3000)]));
+        if (!signal.aborted && isNewer(release.tag_name, current)) {
+            (options.notify ?? (message => process.stderr.write(`${message}\n`)))(updateText(locale, 'available', { current, latest: stableVersion(release.tag_name) }));
+        }
+    }
+    catch { /* Update availability must never make a conversion fail. */ }
+    finally {
+        if (ownsLock)
+            await rm(lock, { force: true }).catch(() => { });
+    }
+}
+export async function downloadAsset(release, asset, directory, fetcher = nativeFetch) {
+    const expected = `https://github.com/${RELEASE_REPO}/releases/download/${release.tag_name}/${asset.name}`;
+    if (!/^[\w.-]+$/.test(asset.name) || asset.browser_download_url !== expected)
+        throw new Error('Unexpected asset URL or filename');
+    if (!Number.isSafeInteger(asset.size) || asset.size <= 0 || asset.size > 2_000_000_000)
+        throw new Error('Invalid download size');
+    if (!/^sha256:[a-f0-9]{64}$/i.test(asset.digest ?? ''))
+        throw new Error('Release asset is missing its SHA-256 digest');
+    await mkdir(directory, { recursive: true });
+    const target = join(directory, asset.name);
+    const temporary = join(directory, `.${asset.name}.${randomUUID()}.part`);
+    const file = await open(temporary, 'wx', 0o600);
+    try {
+        const response = await fetcher(expected, { signal: AbortSignal.timeout(10 * 60 * 1000) });
+        if (!response.ok || !response.body)
+            throw new Error(`Download HTTP ${response.status}`);
+        const hash = createHash('sha256');
+        let size = 0;
+        for await (const chunk of response.body) {
+            size += chunk.byteLength;
+            if (size > asset.size)
+                throw new Error('Download exceeds expected size');
+            hash.update(chunk);
+            await file.writeFile(chunk);
+        }
+        if (size !== asset.size || `sha256:${hash.digest('hex')}` !== asset.digest?.toLowerCase())
+            throw new Error('Download checksum or size mismatch');
+        await file.close();
+        await rename(temporary, target);
+        if (asset.name.endsWith('.AppImage'))
+            await chmod(target, 0o700);
+        return target;
+    }
+    catch (error) {
+        await file.close().catch(() => { });
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+export function runNpm(args, capture, cwd) {
+    return new Promise((done, fail) => {
+        // Windows npm.cmd requires cmd.exe; only fixed arguments and validated
+        // versions are passed to it. Paths are supplied via cwd or npm config env.
+        const child = spawn(process.platform === 'win32' ? 'npm.cmd' : 'npm', args, {
+            cwd, shell: process.platform === 'win32', stdio: capture ? ['ignore', 'pipe', 'pipe'] : ['inherit', 'pipe', 'pipe'],
+        });
+        let output = '';
+        child.stdout?.on('data', chunk => { if (capture)
+            output += chunk;
+        else
+            process.stderr.write(chunk); });
+        child.stderr?.on('data', chunk => { if (!capture)
+            process.stderr.write(chunk); });
+        child.on('error', fail);
+        child.on('exit', code => code === 0 ? done(output.trim()) : fail(new Error(`npm exited with code ${code}`)));
+    });
+}
+export async function installNpm(version, root, runner = runNpm) {
+    // Use the same npm scope/prefix that owns this installation. Never silently
+    // install a second global copy when this one belongs to a local project.
+    const globalRoot = await runner(['root', '--global'], true);
+    const owner = await realpath(dirname(root));
+    if (!globalRoot)
+        throw new Error('npm did not report its global installation directory');
+    const globalOwner = await realpath(globalRoot).catch(() => resolve(globalRoot));
+    if (owner === globalOwner) {
+        await runner(['install', '--global', `execonvert@${stableVersion(version)}`], false);
+    }
+    else {
+        const project = dirname(owner);
+        // A different npm prefix must not be mistaken for a local project.
+        try {
+            await readFile(join(project, 'package.json'), 'utf8');
+        }
+        catch {
+            throw new Error(`Cannot locate the npm installation scope for ${root}. Use the npm/prefix that installed this copy.`);
+        }
+        await runner(['install', `execonvert@${stableVersion(version)}`], false, project);
+    }
+}
+export async function runUpdate(options) {
+    const { current, locale, check, json } = options;
+    let release;
+    try {
+        release = await latestRelease();
+    }
+    catch (error) {
+        throw new Error(updateText(locale, 'network', { message: String(error instanceof Error ? error.message : error) }));
+    }
+    const latest = stableVersion(release.tag_name);
+    const installation = await detectInstallation();
+    const available = isNewer(latest, current);
+    const result = { current, latest, available, installation: installation.kind, url: release.html_url, action: 'checked' };
+    const emit = (text) => { if (!json)
+        process.stdout.write(`${text}\n`); };
+    if (check || !available)
+        emit(updateText(locale, available ? 'available' : 'current', { current, latest }));
+    else if (installation.kind === 'source' || installation.kind === 'unknown') {
+        result.action = 'manual';
+        emit(updateText(locale, installation.kind, { url: release.html_url }));
+    }
+    else if (installation.kind === 'npm') {
+        await installNpm(latest, installation.root);
+        result.action = 'installed';
+        emit(updateText(locale, 'installed', { latest }));
+    }
+    else {
+        const asset = selectAsset(release, installation);
+        if (!asset)
+            throw new Error(updateText(locale, 'missing', { latest, ...installation, url: release.html_url }));
+        const path = await downloadAsset(release, asset, resolve(options.outDir ?? join(updateCacheDir(), 'downloads', latest)));
+        result.action = 'downloaded';
+        result.path = path;
+        result.installationRequired = true;
+        emit(updateText(locale, 'downloaded', { path }));
+        emit(updateText(locale, installation.kind === 'appimage' ? 'appimage' : 'apply'));
+    }
+    if (json)
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "execonvert",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eXeConvert/eXeConvert.github.io.git"
+  },
   "type": "module",
   "bin": {
     "execonvert": "./bin/execonvert.js"
@@ -31,7 +35,10 @@
     "check:cli": "tsc -p tsconfig.cli.json --noEmit",
     "cli": "node ./bin/execonvert.js",
     "sync:exe": "bash scripts/sync-exe-bundles.sh",
-    "prepack": "npm run build:cli"
+    "prepack": "npm run build:cli",
+    "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"
   },
   "dependencies": {
     "@resvg/resvg-js": "^2.6.2",