docviz-builder 0.1.0

package/scripts/capture-preview.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Captura el documento compilado tal y como lo ve un visor real.
+ *
+ * Levanta el servidor de previsualizacion, abre el documento en Chromium y
+ * guarda una captura de pagina completa. Ademas informa de cada imagen que el
+ * navegador no haya podido cargar, que es la comprobacion que exige la
+ * validacion manual ("no hay imagenes rotas").
+ *
+ *   node scripts/capture-preview.mjs <dirCompilado> <documento.md> <salida.png>
+ */
+
+import path from 'node:path';
+import process from 'node:process';
+import { writeFile } from 'node:fs/promises';
+import puppeteer from 'puppeteer-core';
+import { startPreview } from '../dist/build/preview.js';
+import { browserNotFoundHelp, findBrowser } from '../dist/renderers/browser.js';
+
+const [, , dir, document_, output] = process.argv;
+if (dir === undefined || document_ === undefined || output === undefined) {
+  process.stderr.write('uso: node scripts/capture-preview.mjs <dirCompilado> <documento.md> <salida.png>\n');
+  process.exit(2);
+}
+
+const executablePath = findBrowser();
+if (executablePath === undefined) {
+  process.stderr.write(`${browserNotFoundHelp()}\n`);
+  process.exit(1);
+}
+
+const server = await startPreview(path.resolve(dir), 0);
+const browser = await puppeteer.launch({ executablePath, headless: true, args: ['--no-sandbox'] });
+const page = await browser.newPage();
+await page.setViewport({ width: 1200, height: 900, deviceScaleFactor: 1 });
+
+const failed = [];
+page.on('requestfailed', (req) => failed.push(req.url()));
+page.on('response', (res) => {
+  // El favicon no forma parte del documento: su ausencia no es una imagen rota.
+  if (res.status() >= 400 && !res.url().endsWith('/favicon.ico')) {
+    failed.push(`${res.status()} ${res.url()}`);
+  }
+});
+
+await page.goto(new URL(document_, server.url).href, { waitUntil: 'networkidle0' });
+
+// El visor marca las imagenes como `loading="lazy"`: hay que recorrer la pagina
+// y esperar a que todas terminen, o las de mas abajo se medirian como 0x0.
+await page.evaluate(async () => {
+  for (const img of document.querySelectorAll('img')) img.loading = 'eager';
+  await new Promise((resolve) => {
+    let y = 0;
+    const step = () => {
+      y += 600;
+      window.scrollTo(0, y);
+      if (y < document.body.scrollHeight) setTimeout(step, 30);
+      else {
+        window.scrollTo(0, 0);
+        resolve(undefined);
+      }
+    };
+    step();
+  });
+  await Promise.all(
+    [...document.querySelectorAll('img')].map(
+      (img) =>
+        img.complete ||
+        new Promise((resolve) => {
+          img.addEventListener('load', resolve, { once: true });
+          img.addEventListener('error', resolve, { once: true });
+        }),
+    ),
+  );
+});
+
+// Comprueba en el DOM que cada <img> tiene dimensiones reales.
+const images = await page.evaluate(() =>
+  [...document.querySelectorAll('img')].map((img) => ({
+    src: img.getAttribute('src') ?? '',
+    ok: img.complete && img.naturalWidth > 0 && img.naturalHeight > 0,
+    width: img.naturalWidth,
+    height: img.naturalHeight,
+  })),
+);
+
+const png = await page.screenshot({ type: 'png', fullPage: true });
+await writeFile(output, png);
+
+await browser.close();
+await server.close();
+
+const broken = images.filter((i) => !i.ok);
+process.stdout.write(`imagenes en el documento: ${images.length}\n`);
+for (const image of images) {
+  process.stdout.write(`  ${image.ok ? 'OK  ' : 'ROTA'} ${image.width}x${image.height}  ${image.src}\n`);
+}
+if (failed.length > 0) process.stdout.write(`peticiones fallidas: ${failed.join(', ')}\n`);
+process.stdout.write(`captura: ${output}\n`);
+
+process.exit(broken.length === 0 && failed.length === 0 ? 0 : 1);

package/scripts/check-github.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * Comprueba como se veria la documentacion compilada en GitHub.
+ *
+ * GitHub expone la misma API que usa para renderizar Markdown en su web
+ * (`POST /markdown`), asi que se le puede pedir el HTML resultante y verificar
+ * sobre el que las imagenes sobreviven, conservan su texto alternativo y siguen
+ * apuntando a rutas relativas. No hace falta publicar el repositorio ni abrir
+ * un navegador.
+ *
+ *   node scripts/check-github.mjs [dirCompilado] [--repo owner/name]
+ *
+ * Requiere el CLI `gh` autenticado.
+ *
+ * Lo que esta comprobacion **no** puede demostrar: que el servidor de imagenes
+ * de GitHub conserve el `<style>` interno del SVG, del que depende la variante
+ * oscura. Eso solo se ve abriendo el archivo con una sesion iniciada; aqui se
+ * verifica lo verificable y se dice cual es el limite.
+ */
+
+import { execFile } from 'node:child_process';
+import { readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { promisify } from 'node:util';
+import { visit } from 'unist-util-visit';
+import { collectMarkdown } from '../dist/build/builder.js';
+import { parseMarkdown } from '../dist/markdown/scan.js';
+
+const run = promisify(execFile);
+
+const args = process.argv.slice(2);
+const repoIndex = args.indexOf('--repo');
+const repo = repoIndex >= 0 ? args[repoIndex + 1] : 'TilsonF/docviz-builder';
+const dir = path.resolve(args.find((a) => !a.startsWith('--') && a !== repo) ?? 'docs');
+
+/** Pide a GitHub que renderice el Markdown igual que en su web. */
+async function renderizarEnGitHub(markdown) {
+  const payload = path.join(tmpdir(), `docviz-gh-${process.pid}.json`);
+  await writeFile(payload, JSON.stringify({ text: markdown, mode: 'gfm', context: repo }), 'utf8');
+  const { stdout } = await run('gh', ['api', '/markdown', '--method', 'POST', '--input', payload], {
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  return stdout;
+}
+
+const documentos = await collectMarkdown(dir);
+if (documentos.length === 0) {
+  process.stderr.write(`no hay documentos Markdown en ${dir}\n`);
+  process.exit(1);
+}
+
+let problemas = 0;
+let imagenesTotales = 0;
+
+for (const archivo of documentos) {
+  const relativo = path.relative(dir, archivo);
+  const markdown = await readFile(archivo, 'utf8');
+
+  // Se recorre el AST, no el texto: un ejemplo de sintaxis dentro de un bloque
+  // de codigo se parece a una imagen, pero no lo es, y contarlo daria un fallo
+  // donde no lo hay.
+  const arbol = parseMarkdown(markdown);
+  const esperadas = [];
+  let bloquesDeCodigo = 0;
+  visit(arbol, 'image', (nodo) => {
+    esperadas.push({ alt: nodo.alt ?? '', src: nodo.url });
+  });
+  visit(arbol, 'code', () => {
+    bloquesDeCodigo += 1;
+  });
+
+  const html = await renderizarEnGitHub(markdown);
+  const renderizadas = [...html.matchAll(/<img\s[^>]*>/g)].map((m) => m[0]);
+
+  process.stdout.write(`\n${relativo}\n`);
+  process.stdout.write(`  imagenes en el fuente: ${esperadas.length}\n`);
+  process.stdout.write(`  imagenes renderizadas: ${renderizadas.length}\n`);
+  imagenesTotales += esperadas.length;
+
+  if (renderizadas.length !== esperadas.length) {
+    process.stdout.write('  ERROR: GitHub no renderizo todas las imagenes\n');
+    problemas += 1;
+  }
+
+  for (const { alt, src } of esperadas) {
+    const etiqueta = renderizadas.find((t) => t.includes(`src="${src}"`));
+    if (etiqueta === undefined) {
+      process.stdout.write(`  ERROR: no se renderizo ${src}\n`);
+      problemas += 1;
+      continue;
+    }
+    if (!etiqueta.includes(`alt="${alt}"`)) {
+      process.stdout.write(`  ERROR: ${src} perdio su texto alternativo\n`);
+      problemas += 1;
+    }
+    if (/^[a-z][a-z0-9+.-]*:/i.test(src)) {
+      process.stdout.write(`  ERROR: ${src} no es una ruta relativa\n`);
+      problemas += 1;
+    }
+  }
+
+  // Los bloques de codigo que no son diagramas deben seguir siendo codigo.
+  const pre = (html.match(/<pre[\s>]/g) ?? []).length;
+  if (bloquesDeCodigo > 0 && pre === 0) {
+    process.stdout.write('  ERROR: los bloques de codigo no sobrevivieron\n');
+    problemas += 1;
+  }
+
+  if (/<script/i.test(html)) {
+    process.stdout.write('  ERROR: el HTML renderizado contiene un script\n');
+    problemas += 1;
+  }
+}
+
+process.stdout.write(
+  `\n${documentos.length} documento(s), ${imagenesTotales} imagen(es), ${problemas} problema(s)\n`,
+);
+process.stdout.write(
+  '\nComprobado: GitHub renderiza cada imagen, conserva su texto alternativo y\n' +
+    'su ruta relativa, y mantiene los bloques de codigo ajenos.\n' +
+    'No comprobado: si su servidor de imagenes conserva el `<style>` interno del\n' +
+    'SVG, del que depende la variante oscura. Eso exige abrir el archivo en\n' +
+    'github.com con la sesion iniciada.\n',
+);
+
+process.exit(problemas === 0 ? 0 : 1);

package/scripts/eval.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Tipos del script de eval, para poder probarlo desde TypeScript.
+ *
+ * El script es `.mjs` a proposito: se ejecuta con node sin compilar, igual que
+ * el resto de `scripts/`. Esta declaracion solo describe lo que exporta.
+ */
+
+export declare function extraerBloque(texto: string): { lang: string; source: string } | undefined;

package/scripts/eval.mjs

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+/**
+ * Mide si DocViz se deja usar por un modelo de lenguaje.
+ *
+ * Es la metrica del producto y hasta ahora era una intuicion: el catalogo, los
+ * mensajes de error y AGENTS.md existen para que un agente acierte, pero nadie
+ * habia comprobado si acierta. Aqui se mide, sobre los mismos casos, en dos
+ * modos:
+ *
+ *   node scripts/eval.mjs              catalogo (sin red, sin coste)
+ *   node scripts/eval.mjs --modelo     con un modelo de verdad (gasta dinero)
+ *
+ * El modo **catalogo** pregunta a `docviz suggest` que tipo usaria para cada
+ * necesidad. No usa un modelo, pero mide justo lo que un modelo lee para
+ * decidir: los `keywords`, el `purpose` y el `whenToUse` del catalogo. Es
+ * determinista, dura un segundo y por eso puede ser una compuerta de CI.
+ *
+ * El modo **modelo** es la medida real: se le entrega el mismo AGENTS.md que
+ * recibiria en un proyecto, se le pide el bloque y se compila. Si falla, se le
+ * devuelve el error tal cual —con su codigo y su errata senalada— y se le deja
+ * reintentar. Lo que se mide entonces no es solo si acierta, sino si nuestros
+ * mensajes de error le permiten recuperarse.
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { compileDsl } from '../dist/dsl/index.js';
+import { suggestType } from '../dist/mcp/tools.js';
+
+const raiz = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const argv = process.argv.slice(2);
+const opciones = {
+  modelo: argv.includes('--modelo'),
+  json: argv.includes('--json'),
+  modeloId: valorDe('--modelo-id') ?? 'claude-opus-5',
+  particion: valorDe('--particion'),
+  reintentos: Number.parseInt(valorDe('--reintentos') ?? '2', 10),
+  minimo: Number.parseFloat(valorDe('--minimo') ?? '0'),
+  soloCaso: valorDe('--caso'),
+};
+
+function valorDe(bandera) {
+  const i = argv.indexOf(bandera);
+  return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : undefined;
+}
+
+async function cargarCasos() {
+  const todos = JSON.parse(await readFile(path.join(raiz, 'eval', 'casos.json'), 'utf8'));
+  return todos.filter(
+    (c) =>
+      (opciones.soloCaso === undefined || c.id === opciones.soloCaso) &&
+      (opciones.particion === undefined || (c.particion ?? 'entrenamiento') === opciones.particion),
+  );
+}
+
+/** Tipos que se dan por buenos para un caso. */
+const aceptados = (caso) => caso.acepta ?? [caso.tipo];
+
+// --------------------------------------------------------------------------
+// Modo catalogo
+// --------------------------------------------------------------------------
+
+async function evaluarCatalogo() {
+  const casos = await cargarCasos();
+  const filas = casos.map((caso) => {
+    const resultado = suggestType({ need: caso.necesidad, limit: 3 });
+    const propuestos = (resultado.matches ?? []).map((m) => m.type);
+    const validos = aceptados(caso);
+    return {
+      id: caso.id,
+      idioma: caso.idioma ?? 'es',
+      particion: caso.particion ?? 'entrenamiento',
+      esperado: caso.tipo,
+      propuestos,
+      top1: propuestos.length > 0 && validos.includes(propuestos[0]),
+      top3: propuestos.some((t) => validos.includes(t)),
+    };
+  });
+
+  const agrupar = (clave) => {
+    const grupos = {};
+    for (const f of filas) {
+      const g = (grupos[f[clave]] ??= { casos: 0, top1: 0, top3: 0 });
+      g.casos += 1;
+      if (f.top1) g.top1 += 1;
+      if (f.top3) g.top3 += 1;
+    }
+    return grupos;
+  };
+  const porIdioma = agrupar('idioma');
+  const porParticion = agrupar('particion');
+
+  return {
+    modo: 'catalogo',
+    casos: filas.length,
+    top1: filas.filter((f) => f.top1).length,
+    top3: filas.filter((f) => f.top3).length,
+    porIdioma,
+    porParticion,
+    filas,
+  };
+}
+
+// --------------------------------------------------------------------------
+// Modo modelo
+// --------------------------------------------------------------------------
+
+const VALLAS = ['diagram', 'chart', 'architecture'];
+
+/** Primer bloque de DocViz que aparezca en la respuesta. */
+export function extraerBloque(texto) {
+  const re = /```(diagram|chart|architecture)[^\n]*\n([\s\S]*?)```/;
+  const m = re.exec(texto);
+  return m === null ? undefined : { lang: m[1], source: m[2] };
+}
+
+const INSTRUCCIONES = [
+  'Escribe UN solo bloque de DocViz que explique lo que se te pide.',
+  'Responde unicamente con el bloque entre vallas, sin texto antes ni despues.',
+  'Elige el tipo mas adecuado del catalogo que aparece en las instrucciones.',
+].join(' ');
+
+async function evaluarModelo() {
+  const casos = await cargarCasos();
+  const { default: Anthropic } = await import('@anthropic-ai/sdk');
+  const client = new Anthropic();
+  const contrato = await readFile(path.join(raiz, 'AGENTS.md'), 'utf8');
+
+  const filas = [];
+  for (const caso of casos) {
+    const fila = await resolverCaso(client, contrato, caso);
+    filas.push(fila);
+    if (!opciones.json) {
+      const marca = fila.compilaFinal ? (fila.intentos === 1 ? 'ok ' : 'ok*') : 'NO ';
+      process.stdout.write(
+        `  ${marca} ${caso.id.padEnd(16)} ${String(fila.tipoUsado ?? '-').padEnd(16)} ${fila.intentos} intento(s)\n`,
+      );
+    }
+  }
+
+  return {
+    modo: 'modelo',
+    modeloId: opciones.modeloId,
+    casos: filas.length,
+    tipoCorrecto: filas.filter((f) => f.tipoCorrecto).length,
+    compilaPrimera: filas.filter((f) => f.compilaPrimera).length,
+    compilaFinal: filas.filter((f) => f.compilaFinal).length,
+    intentosMedios: filas.reduce((a, f) => a + f.intentos, 0) / (filas.length || 1),
+    filas,
+  };
+}
+
+async function resolverCaso(client, contrato, caso) {
+  const mensajes = [{ role: 'user', content: `${INSTRUCCIONES}\n\nNecesidad: ${caso.necesidad}` }];
+  const fila = {
+    id: caso.id,
+    esperado: caso.tipo,
+    intentos: 0,
+    tipoUsado: undefined,
+    tipoCorrecto: false,
+    compilaPrimera: false,
+    compilaFinal: false,
+    errores: [],
+  };
+
+  for (let intento = 1; intento <= opciones.reintentos + 1; intento += 1) {
+    fila.intentos = intento;
+    const respuesta = await client.messages.create({
+      model: opciones.modeloId,
+      max_tokens: 16000,
+      system: [{ type: 'text', text: contrato, cache_control: { type: 'ephemeral' } }],
+      messages: mensajes,
+    });
+
+    const texto = respuesta.content
+      .filter((b) => b.type === 'text')
+      .map((b) => b.text)
+      .join('\n');
+    const bloque = extraerBloque(texto);
+
+    if (bloque === undefined) {
+      fila.errores.push('la respuesta no contenia ningun bloque de DocViz');
+      mensajes.push({ role: 'assistant', content: texto });
+      mensajes.push({
+        role: 'user',
+        content: `No encuentro ningun bloque entre vallas \`\`\`${VALLAS.join('/')}\`\`\`. Devuelve solo el bloque.`,
+      });
+      continue;
+    }
+
+    // El tipo se anota aunque el bloque no compile: acertar el tipo y
+    // equivocarse en un campo son dos fallos distintos y se corrigen distinto.
+    const declarado = /^\s*type:\s*(\S+)/m.exec(bloque.source);
+    fila.tipoUsado = declarado?.[1] ?? (bloque.lang === 'architecture' ? 'c4-context' : undefined);
+    fila.tipoCorrecto = fila.tipoUsado !== undefined && aceptados(caso).includes(fila.tipoUsado);
+
+    try {
+      compileDsl(bloque.lang, bloque.source);
+      fila.compilaFinal = true;
+      if (intento === 1) fila.compilaPrimera = true;
+      return fila;
+    } catch (err) {
+      // Aqui se mide de verdad la calidad del reporte: se le devuelve el error
+      // tal cual lo veria en su terminal, sin ayuda anadida.
+      const reporte = typeof err.format === 'function' ? err.format() : String(err.message ?? err);
+      fila.errores.push(reporte);
+      mensajes.push({ role: 'assistant', content: texto });
+      mensajes.push({ role: 'user', content: `El bloque no compila:\n\n${reporte}\n\nDevuelve el bloque corregido.` });
+    }
+  }
+
+  return fila;
+}
+
+// --------------------------------------------------------------------------
+
+/**
+ * El cuerpo solo corre si se invoca el script directamente.
+ *
+ * Sin esta guarda, importar el modulo para probar una de sus funciones
+ * ejecutaria el eval entero como efecto secundario.
+ */
+const invocadoDirectamente =
+  process.argv[1] !== undefined && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (invocadoDirectamente) await main();
+
+async function main() {
+const resultado = opciones.modelo ? await evaluarModelo() : await evaluarCatalogo();
+
+if (opciones.json) {
+  process.stdout.write(`${JSON.stringify(resultado, null, 2)}\n`);
+} else if (resultado.modo === 'catalogo') {
+  for (const f of resultado.filas) {
+    if (f.top1) continue;
+    process.stdout.write(
+      `  ${(f.top3 ? 'top3' : 'FALLA').padEnd(5)} ${f.id.padEnd(16)} esperaba ${f.esperado.padEnd(16)} propuso ${f.propuestos.join(', ') || '(nada)'}\n`,
+    );
+  }
+  const pct = (n, total) => ((n / total) * 100).toFixed(1);
+  process.stdout.write(
+    `\ncatalogo: ${resultado.casos} casos\n` +
+      `  acierto en la primera propuesta: ${resultado.top1}/${resultado.casos}  (${pct(resultado.top1, resultado.casos)} %)\n` +
+      `  acierto entre las tres primeras: ${resultado.top3}/${resultado.casos}  (${pct(resultado.top3, resultado.casos)} %)\n`,
+  );
+  // El desglose por idioma no es decorativo: el catalogo se escribio en
+  // español y las palabras en ingles se anadieron despues, asi que la unica
+  // forma de saber si sirven de algo es medirlas por separado.
+  for (const [idioma, d] of Object.entries(resultado.porIdioma).sort()) {
+    process.stdout.write(
+      `    ${idioma}: ${d.casos} casos  ->  ${pct(d.top1, d.casos)} % / ${pct(d.top3, d.casos)} %\n`,
+    );
+  }
+  // La particion reservada es la unica cifra que se puede citar: los casos de
+  // entrenamiento se han mirado al ajustar la puntuacion, y lo que se ajusta
+  // mirando deja de medir.
+  process.stdout.write('\n');
+  for (const [particion, d] of Object.entries(resultado.porParticion).sort()) {
+    process.stdout.write(
+      `    ${particion.padEnd(14)} ${String(d.casos).padStart(2)} casos  ->  ${pct(d.top1, d.casos)} % / ${pct(d.top3, d.casos)} %\n`,
+    );
+  }
+} else {
+  const pct = (n) => ((n / resultado.casos) * 100).toFixed(1);
+  process.stdout.write(
+    `\nmodelo ${resultado.modeloId}: ${resultado.casos} casos\n` +
+      `  tipo correcto:        ${resultado.tipoCorrecto}/${resultado.casos}  (${pct(resultado.tipoCorrecto)} %)\n` +
+      `  compila a la primera: ${resultado.compilaPrimera}/${resultado.casos}  (${pct(resultado.compilaPrimera)} %)\n` +
+      `  compila al final:     ${resultado.compilaFinal}/${resultado.casos}  (${pct(resultado.compilaFinal)} %)\n` +
+      `  intentos de media:    ${resultado.intentosMedios.toFixed(2)}\n`,
+  );
+}
+
+// La compuerta mide el acierto entre las tres primeras: un agente ve las tres.
+const medida = resultado.modo === 'catalogo' ? resultado.top3 / resultado.casos : resultado.compilaFinal / resultado.casos;
+if (opciones.minimo > 0 && medida < opciones.minimo) {
+  process.stderr.write(
+    `\nla medida (${(medida * 100).toFixed(1)} %) esta por debajo del minimo exigido (${(opciones.minimo * 100).toFixed(1)} %)\n`,
+  );
+  process.exit(1);
+}
+}

package/scripts/fetch-plantuml.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * Descarga `vendor/plantuml.jar` desde Maven Central.
+ *
+ * Es la unica operacion del proyecto que usa la red, y ocurre una sola vez
+ * durante la instalacion: despues, el build compila sin conexion. El jar no se
+ * versiona en el repositorio porque ocupa unos 26 MB.
+ *
+ *   node scripts/fetch-plantuml.mjs [version]
+ */
+
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_VERSION = '1.2026.0';
+
+/**
+ * Digest esperado de cada version conocida.
+ *
+ * Sin esto, la unica garantia de que el jar es el que dice ser es el TLS de
+ * Maven Central. Es el unico punto de DocViz que trae bytes de fuera y los deja
+ * listos para ejecutarse en una JVM, asi que se comprueba contra un valor
+ * fijado en el repositorio y verificado a mano contra los checksums publicados
+ * (`plantuml-<version>.jar.sha256`).
+ *
+ * Para una version que no este aqui, pasa el digest con `--sha256 <hex>` o
+ * `DOCVIZ_PLANTUML_SHA256`. Descargar sin verificar exige decirlo en voz alta.
+ */
+const DIGESTS = {
+  '1.2026.0': 'b3da2f352a835615ecb63eb754930f8aab57363d5fe1a0660bf2a12827b6b553',
+};
+
+const args = process.argv.slice(2);
+const flag = (nombre) => {
+  const i = args.indexOf(nombre);
+  return i >= 0 && args[i + 1] !== undefined ? args[i + 1] : undefined;
+};
+const sinVerificar = args.includes('--sin-verificar');
+const version = args.find((a) => !a.startsWith('--') && args[args.indexOf(a) - 1] !== '--sha256')
+  ?? process.env['DOCVIZ_PLANTUML_VERSION']
+  ?? DEFAULT_VERSION;
+const esperado = (flag('--sha256') ?? process.env['DOCVIZ_PLANTUML_SHA256'] ?? DIGESTS[version])?.toLowerCase();
+
+if (esperado === undefined && !sinVerificar) {
+  process.stderr.write(
+    `no hay digest conocido para PlantUML ${version}.\n` +
+      'Consulta el checksum publicado:\n' +
+      `  curl -s https://repo1.maven.org/maven2/net/sourceforge/plantuml/plantuml/${version}/plantuml-${version}.jar.sha256\n` +
+      'y pasalo con --sha256 <hex>, o descarga sin verificar con --sin-verificar.\n',
+  );
+  process.exit(1);
+}
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const target = path.join(root, 'vendor', 'plantuml.jar');
+const url = `https://repo1.maven.org/maven2/net/sourceforge/plantuml/plantuml/${version}/plantuml-${version}.jar`;
+
+// Si ya existe un jar utilizable, no se vuelve a descargar.
+try {
+  const existing = await readFile(target);
+  if (existing.byteLength > 1_000_000) {
+    process.stdout.write(`plantuml.jar ya presente (${(existing.byteLength / 1e6).toFixed(1)} MB): ${target}\n`);
+    process.exit(0);
+  }
+} catch {
+  // no existe: se descarga
+}
+
+process.stdout.write(`descargando PlantUML ${version}\n  desde ${url}\n`);
+
+let response;
+try {
+  response = await fetch(url, { redirect: 'follow' });
+} catch (err) {
+  process.stderr.write(
+    `no se pudo contactar con Maven Central: ${err instanceof Error ? err.message : String(err)}\n` +
+      'si tu organizacion distribuye el jar, colocalo en vendor/plantuml.jar o apuntalo\n' +
+      'con renderers.plantuml.jar en docviz.config.yaml\n',
+  );
+  process.exit(1);
+}
+
+if (!response.ok) {
+  process.stderr.write(`Maven Central respondio ${response.status} ${response.statusText}\n`);
+  process.exit(1);
+}
+
+const bytes = Buffer.from(await response.arrayBuffer());
+// Un jar de PlantUML pesa decenas de MB: cualquier cosa menor es una pagina de error.
+if (bytes.byteLength < 1_000_000) {
+  process.stderr.write(`la descarga solo trajo ${bytes.byteLength} bytes; no parece un jar\n`);
+  process.exit(1);
+}
+if (bytes.subarray(0, 2).toString('latin1') !== 'PK') {
+  process.stderr.write('el archivo descargado no es un jar valido\n');
+  process.exit(1);
+}
+
+const digest = createHash('sha256').update(bytes).digest('hex');
+
+// La comprobacion va ANTES de escribir: un jar que no es el esperado no debe
+// llegar al disco, porque el siguiente build lo daria por bueno.
+if (esperado !== undefined && digest !== esperado) {
+  process.stderr.write(
+    'el jar descargado no coincide con el digest esperado; no se ha escrito nada.\n' +
+      `  esperado: ${esperado}\n` +
+      `  obtenido: ${digest}\n` +
+      'Puede ser una version distinta, una descarga corrupta o un intermediario.\n',
+  );
+  process.exit(1);
+}
+
+await mkdir(path.dirname(target), { recursive: true });
+await writeFile(target, bytes);
+
+process.stdout.write(
+  `listo: ${target}\n  tamano: ${(bytes.byteLength / 1e6).toFixed(1)} MB\n` +
+    `  sha256: ${digest}${esperado !== undefined ? ' (verificado)' : ' (SIN VERIFICAR)'}\n`,
+);