bibliotech catalogo listar --formato=csv | grep "Java" | wc -l
cat isbns.txt | bibliotech catalogo importar --desde-stdin
bibliotech informe multas --formato=json | jq '.[] | select(.importe > 10)'

Error: NullPointerException

Error: no se encontró ningún material con ISBN 978-0000000009.

  Causa: el ISBN no existe en el catálogo.
  Sugerencia: comprueba el ISBN con 'bibliotech catalogo buscar --titulo="..."'
              o impórtalo con 'bibliotech catalogo importar'.

public static void main(String[] args) {
    String formato = "tabla";
    boolean verboso = false;
    String isbn = null;

    for (int i = 0; i < args.length; i++) {
        switch (args[i]) {
            case "--formato" -> formato = args[++i];
            case "-v", "--verboso" -> verboso = true;
            case "--isbn" -> isbn = args[++i];
            default -> {
                System.err.println("Opción desconocida: " + args[i]);
                System.exit(2);
            }
        }
    }
    // …
}

<dependencies>
  <dependency>
    <groupId>com.nexussoftware</groupId>
    <artifactId>bibliotech-aplicacion</artifactId>
  </dependency>
  <dependency>
    <groupId>com.nexussoftware</groupId>
    <artifactId>bibliotech-infraestructura</artifactId>
  </dependency>

  <dependency>
    <groupId>info.picocli</groupId>
    <artifactId>picocli-spring-boot-starter</artifactId>   <!-- trae picocli + integración -->
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>           <!-- sin 'web': esto no es un servidor -->
  </dependency>
</dependencies>

package com.nexussoftware.bibliotech.consola;

import picocli.CommandLine;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;
import picocli.CommandLine.Parameters;
import java.util.concurrent.Callable;

@Command(
    name = "bibliotech",                          // cómo se invoca
    mixinStandardHelpOptions = true,              // añade --help y --version gratis
    version = "BiblioTech CLI 1.0.0",
    description = "Herramienta de gestión de la biblioteca técnica de Nexus Software.")
public class Ejemplo implements Callable<Integer> {   // Callable<Integer>: el int es el código de salida

    @Parameters(index = "0", description = "ISBN del material a consultar.")
    private String isbn;

    @Option(names = {"-f", "--formato"}, defaultValue = "tabla",
            description = "Formato de salida: ${COMPLETION-CANDIDATES}. Por defecto: ${DEFAULT-VALUE}")
    private Formato formato;

    @Override
    public Integer call() {
        System.out.println("Consultando " + isbn + " en formato " + formato);
        return 0;                                  // 0 = éxito
    }

    public static void main(String[] args) {
        int codigo = new CommandLine(new Ejemplo()).execute(args);
        System.exit(codigo);
    }
}

$ java -jar ejemplo.jar --help
Usage: bibliotech [-hV] [-f=<formato>] <isbn>
Herramienta de gestión de la biblioteca técnica de Nexus Software.
      <isbn>          ISBN del material a consultar.
  -f, --formato=<formato>
                      Formato de salida: TABLA, CSV, JSON. Por defecto: TABLA
  -h, --help          Show this help message and exit.
  -V, --version       Print version information and exit.

@Command(name = "prestamo")
class OpcionesEjemplo {

    // Booleana: su sola presencia la pone a true
    @Option(names = {"-v", "--verboso"}, description = "Muestra detalle de la ejecución.")
    boolean verboso;

    // Obligatoria: si falta, Picocli produce un error claro
    @Option(names = "--isbn", required = true, description = "ISBN del material.")
    String isbn;

    // Con valor por defecto
    @Option(names = "--dias", defaultValue = "15", description = "Duración en días.")
    int dias;

    // Tipo de java.time: conversión automática desde ISO-8601
    @Option(names = "--desde", description = "Fecha de inicio (yyyy-MM-dd).")
    LocalDate desde;

    // Enum: Picocli valida los valores permitidos y los lista en la ayuda
    @Option(names = "--formato", defaultValue = "TABLA")
    Formato formato;

    // Repetible: --etiqueta java --etiqueta diseño
    @Option(names = "--etiqueta", description = "Etiqueta (repetible).")
    List<String> etiquetas = new ArrayList<>();

    // Con aridad: exactamente dos valores
    @Option(names = "--rango", arity = "2", paramLabel = "<desde> <hasta>")
    int[] rango;

    // Mapa: --propiedad clave=valor
    @Option(names = "-D", description = "Propiedad adicional.")
    Map<String, String> propiedades = new LinkedHashMap<>();

    // Sensible: Picocli la pide por teclado sin mostrarla si no se pasa
    @Option(names = "--clave", interactive = true, arity = "0..1")
    char[] clave;

    // Posicionales: todos los restantes
    @Parameters(index = "0", description = "Fichero de entrada.")
    Path fichero;

    @Parameters(index = "1..*", description = "ISBNs adicionales.")
    List<String> isbnsExtra;
}

static class OrigenDatos {
    @Option(names = "--fichero", required = true) Path fichero;
    @Option(names = "--url", required = true) URI url;
    @Option(names = "--stdin", required = true) boolean stdin;
}

@ArgGroup(exclusive = true, multiplicity = "1")   // exactamente uno de los tres
OrigenDatos origen;

/** Convierte el texto de la línea de comandos en el objeto de valor del dominio. */
public class ConversorIsbn implements CommandLine.ITypeConverter<Isbn> {

    @Override
    public Isbn convert(String valor) {
        try {
            return Isbn.de(valor);          // el objeto de valor ya valida (12-02)
        } catch (IsbnInvalidoException e) {
            // TypeConversionException produce un mensaje de uso, no una traza
            throw new CommandLine.TypeConversionException(
                "'" + valor + "' no es un ISBN-13 válido. Formato esperado: 978-XXXXXXXXXX");
        }
    }
}

@Option(names = "--isbn", required = true, converter = ConversorIsbn.class)
private Isbn isbn;      // ¡el campo es del tipo del dominio, no String!

$ bibliotech prestamo crear --isbn=1234 --empleado=1
Invalid value for option '--isbn': '1234' no es un ISBN-13 válido.
Formato esperado: 978-XXXXXXXXXX
Usage: bibliotech prestamo crear [-hV] --empleado=<id> --isbn=<isbn> [--dias=<n>]
…

@Spec CommandLine.Model.CommandSpec spec;

private void validar() {
    if (desde != null && hasta != null && desde.isAfter(hasta)) {
        throw new CommandLine.ParameterException(spec.commandLine(),
            "--desde (" + desde + ") no puede ser posterior a --hasta (" + hasta + ")");
    }
}

@Command(
    name = "bibliotech",
    mixinStandardHelpOptions = true,
    version = "BiblioTech CLI 1.0.0",
    description = "Gestión de la biblioteca técnica de Nexus Software.",
    subcommands = {
        ComandoCatalogo.class,
        ComandoPrestamo.class,
        ComandoAvisos.class,
        ComandoInforme.class,
        CommandLine.HelpCommand.class          // 'bibliotech help catalogo'
    })
@Component
public class ComandoRaiz implements Callable<Integer> {

    @Override
    public Integer call() {
        // Sin subcomando, mostrar la ayuda y devolver error de uso:
        // así un script sabe que la invocación estaba incompleta.
        CommandLine.usage(this, System.out);
        return CodigoSalida.ERROR_USO;
    }
}

@Command(name = "catalogo",
         description = "Operaciones sobre el catálogo de materiales.",
         subcommands = {ComandoCatalogoListar.class, ComandoCatalogoBuscar.class,
                        ComandoCatalogoImportar.class, ComandoCatalogoFicha.class})
@Component
public class ComandoCatalogo implements Callable<Integer> {
    @Override public Integer call() {
        CommandLine.usage(this, System.out);
        return CodigoSalida.ERROR_USO;
    }
}

@Command(name = "bibliotech", …)
public class ComandoRaiz {

    @Option(names = {"-f", "--formato"}, scope = CommandLine.ScopeType.INHERIT,
            defaultValue = "TABLA", description = "Formato de salida: ${COMPLETION-CANDIDATES}")
    Formato formato;

    @Option(names = {"-q", "--silencioso"}, scope = CommandLine.ScopeType.INHERIT,
            description = "Solo errores.")
    boolean silencioso;

    @Option(names = {"-v", "--verboso"}, scope = CommandLine.ScopeType.INHERIT,
            description = "Detalle de la ejecución.")
    boolean verboso;
}

@Command(name = "importar",
    description = "Importa materiales al catálogo desde un fichero o desde la entrada estándar.",
    footerHeading = "%nEjemplos:%n",
    footer = {
        "  bibliotech catalogo importar catalogo.csv",
        "  bibliotech catalogo importar --formato-entrada=json datos.json --simular",
        "  cat isbns.txt | bibliotech catalogo importar --desde-stdin --enriquecer",
        "",
        "Códigos de salida: 0 correcto, 1 error, 2 uso incorrecto, 4 importación parcial."
    })
class ComandoCatalogoImportar implements Callable<Integer> { … }

# Generar el script (una vez, en la construcción)
java -cp bibliotech-consola.jar picocli.AutoComplete \
     -n bibliotech com.nexussoftware.bibliotech.consola.ComandoRaiz

# Activarlo en la sesión
source bibliotech_completion

# Ahora funciona el tabulador
$ bibliotech cat<TAB>          → bibliotech catalogo
$ bibliotech catalogo <TAB>    → buscar  ficha  importar  listar
$ bibliotech catalogo listar --formato=<TAB>  → TABLA  CSV  JSON

package com.nexussoftware.bibliotech.consola;

@SpringBootApplication(scanBasePackages = "com.nexussoftware.bibliotech")
public class BiblioTechCli implements CommandLineRunner, ExitCodeGenerator {

    private final ComandoRaiz comandoRaiz;
    private final CommandLine.IFactory fabrica;    // la aporta el starter de Picocli
    private int codigoSalida;

    public BiblioTechCli(ComandoRaiz comandoRaiz, CommandLine.IFactory fabrica) {
        this.comandoRaiz = comandoRaiz;
        this.fabrica = fabrica;
    }

    @Override
    public void run(String... args) {
        this.codigoSalida = new CommandLine(comandoRaiz, fabrica)
                .setCaseInsensitiveEnumValuesAllowed(true)     // --formato=json y JSON
                .setExecutionExceptionHandler(new ManejadorErroresCli())
                .execute(args);
    }

    @Override
    public int getExitCode() { return codigoSalida; }

    public static void main(String[] args) {
        // SpringApplication.exit devuelve el código del ExitCodeGenerator,
        // y cierra el contexto ordenadamente antes de salir.
        System.exit(SpringApplication.exit(SpringApplication.run(BiblioTechCli.class, args)));
    }
}

@Command(name = "crear", description = "Crea un préstamo de un material a un empleado.")
@Component
public class ComandoPrestamoCrear implements Callable<Integer> {

    private final GestionarPrestamos gestor;      // ¡inyección por constructor, como siempre!
    private final Salida salida;

    public ComandoPrestamoCrear(GestionarPrestamos gestor, Salida salida) {
        this.gestor = gestor;
        this.salida = salida;
    }

    @Option(names = "--isbn", required = true, converter = ConversorIsbn.class)
    private Isbn isbn;

    @Option(names = "--empleado", required = true, paramLabel = "<id>")
    private Long idEmpleado;

    @Option(names = "--dias", description = "Duración. Por defecto, la del tipo de material.")
    private Integer dias;

    @Override
    public Integer call() {
        Prestamo prestamo = gestor.prestar(isbn, idEmpleado, dias);
        salida.exito("Préstamo #%d creado. Vence el %s."
                .formatted(prestamo.getId(), prestamo.getFechaVencimiento()));
        return CodigoSalida.OK;
    }
}

spring:
  main:
    web-application-type: none      # sin Tomcat
    banner-mode: off                # sin banner ASCII contaminando la salida
  output:
    ansi:
      enabled: detect               # colores solo si el terminal los soporta

logging:
  pattern:
    console: "%d{HH:mm:ss} %-5level %msg%n"
  level:
    root: WARN                      # una CLI silenciosa por defecto
    com.nexussoftware.bibliotech: INFO

@Command(name = "listar",
    description = "Lista los materiales del catálogo.",
    footerHeading = "%nEjemplos:%n",
    footer = {
        "  bibliotech catalogo listar --tipo=LIBRO --disponibles",
        "  bibliotech catalogo listar --formato=csv > catalogo.csv",
        "  bibliotech catalogo listar --formato=json | jq '.[].titulo'"
    })
@Component
public class ComandoCatalogoListar implements Callable<Integer> {

    private final ConsultarCatalogo catalogo;
    private final Salida salida;

    public ComandoCatalogoListar(ConsultarCatalogo catalogo, Salida salida) {
        this.catalogo = catalogo;
        this.salida = salida;
    }

    @Option(names = "--tipo", description = "Filtrar por tipo: ${COMPLETION-CANDIDATES}")
    private TipoMaterial tipo;

    @Option(names = "--disponibles", description = "Solo materiales con unidades libres.")
    private boolean soloDisponibles;

    @Option(names = "--limite", defaultValue = "50",
            description = "Número máximo de resultados. Por defecto: ${DEFAULT-VALUE}")
    private int limite;

    @Option(names = "--ordenar-por", defaultValue = "TITULO",
            description = "Criterio de orden: ${COMPLETION-CANDIDATES}")
    private CriterioOrden orden;

    @Override
    public Integer call() {
        var criterio = CriterioBusqueda.builder()          // Builder de 12-02
                .tipo(tipo)
                .soloDisponibles(soloDisponibles)
                .construir();

        List<Material> resultados = catalogo.buscar(criterio, orden, limite);

        if (resultados.isEmpty()) {
            salida.aviso("No se encontró ningún material con esos criterios.");
            return CodigoSalida.SIN_RESULTADOS;            // 3: distinto de error
        }

        salida.escribirMateriales(resultados);             // el formato lo decide Salida
        salida.info("%d materiales.".formatted(resultados.size()));
        return CodigoSalida.OK;
    }
}

@Command(name = "shell", description = "Modo interactivo. Escribe 'salir' para terminar.")
@Component
public class ComandoShell implements Callable<Integer> {

    private final ComandoRaiz raiz;
    private final CommandLine.IFactory fabrica;

    @Override
    public Integer call() {
        // Console es null si la entrada está redirigida: entonces el shell no tiene sentido
        Console consola = System.console();
        if (consola == null) {
            System.err.println("El modo interactivo requiere un terminal.");
            return CodigoSalida.ERROR_USO;
        }

        System.out.println("BiblioTech 1.0.0 — escribe 'ayuda' o 'salir'.");
        CommandLine cl = new CommandLine(raiz, fabrica);

        while (true) {
            String linea = consola.readLine("bibliotech> ");
            if (linea == null || linea.isBlank()) continue;
            if (linea.equals("salir") || linea.equals("exit")) return CodigoSalida.OK;
            if (linea.equals("ayuda")) { cl.usage(System.out); continue; }

            // Reutiliza EXACTAMENTE el mismo parseo y los mismos comandos
            cl.execute(trocear(linea));
        }
    }

    /** Trocea respetando las comillas: buscar --titulo="Java Efectivo" */
    private String[] trocear(String linea) {
        List<String> partes = new ArrayList<>();
        Matcher m = Pattern.compile("\"([^\"]*)\"|(\\S+)").matcher(linea);
        while (m.find()) {
            partes.add(m.group(1) != null ? m.group(1) : m.group(2));
        }
        return partes.toArray(String[]::new);
    }
}

@Option(names = "--desde-stdin", description = "Lee los ISBN de la entrada estándar, uno por línea.")
private boolean desdeStdin;

@Parameters(index = "0", arity = "0..1", description = "Fichero de entrada.")
private Path fichero;

private List<String> leerEntrada() throws IOException {
    if (desdeStdin) {
        // Ojo con la codificación: en Java 18+ el defecto es UTF-8, pero ser explícito no sobra
        try (BufferedReader lector = new BufferedReader(
                new InputStreamReader(System.in, StandardCharsets.UTF_8))) {
            return lector.lines()
                    .map(String::strip)
                    .filter(l -> !l.isEmpty() && !l.startsWith("#"))   // ignorar comentarios
                    .toList();
        }
    }
    if (fichero != null) {
        return Files.readAllLines(fichero, StandardCharsets.UTF_8);
    }
    throw new CommandLine.ParameterException(spec.commandLine(),
        "Indica un fichero de entrada o usa --desde-stdin.");
}

/** true si stdout va a un terminal; false si va a un fichero o a otro proceso. */
public static boolean esTerminal() {
    return System.console() != null;
}

$ bibliotech catalogo listar                      # terminal: colores, cabeceras, totales
$ bibliotech catalogo listar > catalogo.txt       # fichero: sin colores ni adornos
$ bibliotech catalogo listar | grep Java          # tubería: idem

# El resultado va al fichero; los avisos siguen viéndose en pantalla
bibliotech catalogo importar datos.csv > resultado.json 2> importacion.log

# Encadenar sin que nada se contamine
bibliotech informe multas --formato=json | jq '[.[] | select(.importe > 10)] | length'

# Usar la salida de un comando como entrada de otro
bibliotech prestamo listar --vencidos --formato=csv | cut -d';' -f2 | \
  bibliotech avisos enviar --desde-stdin

bibliotech avisos enviar || echo "FALLO: revisa el log"    # || se ejecuta si el código != 0

public final class CodigoSalida {
    public static final int OK = 0;
    public static final int ERROR = 1;
    public static final int ERROR_USO = 2;
    public static final int SIN_RESULTADOS = 3;
    public static final int PARCIAL = 4;
    public static final int NO_ENCONTRADO = 5;
    public static final int CONFLICTO = 6;
    public static final int NO_DISPONIBLE = 7;
    public static final int INTERRUMPIDO = 130;

    private CodigoSalida() { }
}

#!/usr/bin/env bash
# Reintentar solo cuando tiene sentido
for intento in 1 2 3; do
  bibliotech catalogo importar --enriquecer datos.csv
  codigo=$?
  case $codigo in
    0) echo "Importación correcta"; exit 0 ;;
    7) echo "Servicio no disponible; reintento $intento"; sleep $((intento * 30)) ;;
    *) echo "Error no recuperable (código $codigo)"; exit $codigo ;;
  esac
done
exit 7

@Component
public class Salida {

    private final ObjectMapper json;         // Jackson, del módulo 11: bean único
    private final PrintStream out;
    private final PrintStream err;

    private Formato formato = Formato.TABLA;
    private Nivel nivel = Nivel.NORMAL;
    private boolean color = true;

    public Salida(ObjectMapper json) {
        this.json = json;
        // Codificación explícita: sin esto, los acentos se rompen al redirigir en Windows
        this.out = new PrintStream(new FileOutputStream(FileDescriptor.out), true, UTF_8);
        this.err = new PrintStream(new FileOutputStream(FileDescriptor.err), true, UTF_8);
    }

    public void escribirMateriales(List<Material> materiales) {
        switch (formato) {
            case TABLA -> tabla(materiales);
            case CSV   -> csv(materiales);
            case JSON  -> json(materiales.stream().map(MaterialDto::desde).toList());
        }
    }
    // …
}

private void tabla(List<Material> materiales) {
    // 1. Calcular el ancho de cada columna: el del contenido más largo, con un máximo
    int anchoTitulo = Math.min(45, Math.max(6,
            materiales.stream().mapToInt(m -> m.getTitulo().length()).max().orElse(6)));

    String formatoFila = "%-17s  %-" + anchoTitulo + "s  %-8s  %5s%n";

    // 2. Cabecera solo si NO es una tubería y no estamos en modo silencioso
    if (mostrarDecoracion()) {
        out.printf(formatoFila, "ISBN", "TÍTULO", "TIPO", "LIBRES");
        out.println("-".repeat(17 + anchoTitulo + 8 + 5 + 6));
    }

    // 3. Filas
    for (Material m : materiales) {
        out.printf(formatoFila,
                m.getIsbn().valor(),
                recortar(m.getTitulo(), anchoTitulo),
                m.tipo(),
                colorearDisponibilidad(m.unidadesDisponibles()));
    }
}

/** Recorta con puntos suspensivos para no descuadrar la tabla. */
private String recortar(String texto, int max) {
    return texto.length() <= max ? texto : texto.substring(0, max - 1) + "…";
}

ISBN               TÍTULO                                TIPO      LIBRES
-----------------------------------------------------------------------
978-0000000001     Java Efectivo                         LIBRO          2
978-0000000002     Patrones de Diseño                    LIBRO          0
978-0000000003     Refactorización                       LIBRO          1

private void csv(List<Material> materiales) {
    if (mostrarDecoracion()) out.println("isbn;titulo;tipo;disponibles");
    for (Material m : materiales) {
        out.printf("%s;%s;%s;%d%n",
                m.getIsbn().valor(), escapar(m.getTitulo()), m.tipo(), m.unidadesDisponibles());
    }
}

private String escapar(String valor) {
    // Si contiene separador, comillas o saltos de línea, hay que entrecomillar y duplicar comillas
    if (valor.contains(";") || valor.contains("\"") || valor.contains("\n")) {
        return '"' + valor.replace("\"", "\"\"") + '"';
    }
    return valor;
}

private void json(Object valor) {
    try {
        // Sin indentar si es una tubería (más compacto); indentado si lo lee una persona
        ObjectWriter escritor = esTerminal()
                ? json.writerWithDefaultPrettyPrinter()
                : json.writer();
        out.println(escritor.writeValueAsString(valor));
    } catch (JsonProcessingException e) {
        throw new SalidaFallidaException("No se pudo serializar el resultado", e);
    }
}

public enum Nivel { SILENCIOSO, NORMAL, VERBOSO, TRAZA }

@Component
public class Salida {

    /** Resultado: SIEMPRE a stdout, incluso en modo silencioso. Es lo que pidió el usuario. */
    public void resultado(String texto) { out.println(texto); }

    /** Información contextual: a stderr, para no contaminar la tubería. */
    public void info(String texto) {
        if (nivel.ordinal() >= Nivel.NORMAL.ordinal()) err.println(texto);
    }

    /** Detalle de ejecución: solo con -v. */
    public void detalle(String texto) {
        if (nivel.ordinal() >= Nivel.VERBOSO.ordinal()) err.println(gris("  " + texto));
    }

    public void aviso(String texto)  { err.println(amarillo("Aviso: ") + texto); }
    public void error(String texto)  { err.println(rojo("Error: ") + texto); }
    public void exito(String texto)  { if (nivel != Nivel.SILENCIOSO) err.println(verde("✓ ") + texto); }
}

@Option(names = {"-v", "--verboso"}, scope = ScopeType.INHERIT)
void setVerboso(boolean[] veces) {
    Nivel nivel = veces.length >= 2 ? Nivel.TRAZA : Nivel.VERBOSO;
    salida.setNivel(nivel);
    if (nivel == Nivel.TRAZA) {
        // Subir el nivel de Logback en caliente (11-07)
        ((ch.qos.logback.classic.Logger) LoggerFactory.getLogger("com.nexussoftware.bibliotech"))
            .setLevel(ch.qos.logback.classic.Level.DEBUG);
    }
}

@Command(name = "importar", description = "Importa materiales al catálogo.")
@Component
public class ComandoCatalogoImportar implements Callable<Integer> {

    private final ImportadorCatalogo importador;
    private final Salida salida;

    @Parameters(index = "0", arity = "0..1") private Path fichero;
    @Option(names = "--desde-stdin") private boolean desdeStdin;
    @Option(names = "--enriquecer", description = "Completa los metadatos desde la API externa.")
    private boolean enriquecer;
    @Option(names = "--simular", description = "No escribe nada; muestra lo que haría.")
    private boolean simular;

    @Override
    public Integer call() throws Exception {
        List<RegistroImportacion> registros = leerEntrada();
        salida.info("Importando %d registros%s…"
                .formatted(registros.size(), simular ? " (SIMULACIÓN)" : ""));

        var progreso = new BarraProgreso(registros.size(), salida);
        var correctos = new AtomicInteger();                 // módulo 8
        var errores = Collections.synchronizedList(new ArrayList<ErrorImportacion>());

        // Hilos virtuales: miles de tareas bloqueantes de E/S sin agotar el sistema
        try (var ejecutor = Executors.newVirtualThreadPerTaskExecutor()) {
            for (RegistroImportacion registro : registros) {
                ejecutor.submit(() -> {
                    try {
                        if (!simular) importador.importar(registro, enriquecer);
                        correctos.incrementAndGet();
                    } catch (BiblioTechException e) {
                        errores.add(ErrorImportacion.de(registro, e));
                    } finally {
                        progreso.avanzar();
                    }
                });
            }
        }   // el cierre del try-with-resources espera a que TODAS terminen

        progreso.terminar();

        salida.escribirResultadoImportacion(correctos.get(), errores);

        if (errores.isEmpty()) return CodigoSalida.OK;
        if (correctos.get() == 0) return CodigoSalida.ERROR;
        return CodigoSalida.PARCIAL;                          // el 4 de la tabla
    }
}

public class BarraProgreso {

    private static final int ANCHO = 40;

    private final int total;
    private final Salida salida;
    private final AtomicInteger actual = new AtomicInteger();
    private final long inicio = System.nanoTime();
    private final boolean activa;
    private volatile long ultimoRepintado;

    public BarraProgreso(int total, Salida salida) {
        this.total = total;
        this.salida = salida;
        // DECISIÓN 1: solo si hay terminal y no estamos en silencioso.
        // Una barra de progreso en un fichero de log es basura ilegible.
        this.activa = salida.esTerminal() && salida.nivel() != Nivel.SILENCIOSO;
    }

    public void avanzar() {
        int n = actual.incrementAndGet();
        if (!activa) return;

        // DECISIÓN 2: limitar el repintado. Repintar 5.000 veces por segundo
        // consume más CPU que el propio trabajo.
        long ahora = System.nanoTime();
        if (n < total && ahora - ultimoRepintado < 100_000_000L) return;   // 100 ms
        ultimoRepintado = ahora;

        pintar(n);
    }

    private void pintar(int n) {
        int llenos = (int) ((double) n / total * ANCHO);
        long segundos = (System.nanoTime() - inicio) / 1_000_000_000L;
        long restantes = n > 0 ? segundos * (total - n) / n : 0;

        // DECISIÓN 3: a stderr, no a stdout. El progreso NO es el resultado.
        // \r vuelve al principio de la línea sin saltar: la barra se sobreescribe.
        salida.err().printf("\r[%s%s] %d/%d (%d%%) ETA %ds  ",
                "=".repeat(llenos), " ".repeat(ANCHO - llenos),
                n, total, n * 100 / total, restantes);
    }

    public void terminar() {
        if (activa) salida.err().println();     // cerrar la línea de la barra
    }
}

[========================>               ] 3120/5000 (62%) ETA 47s

@Component
public class GestorCancelacion {

    private static final Logger log = LoggerFactory.getLogger(GestorCancelacion.class);

    private final AtomicBoolean cancelado = new AtomicBoolean(false);
    private final CountDownLatch trabajoTerminado = new CountDownLatch(1);

    @PostConstruct
    void registrar() {
        Runtime.getRuntime().addShutdownHook(new Thread(this::alRecibirSenal, "cancelacion"));
    }

    private void alRecibirSenal() {
        cancelado.set(true);
        System.err.println("\nCancelando… (pulsa Ctrl+C de nuevo para forzar)");
        try {
            // Dar un margen para terminar ordenadamente, pero NO esperar indefinidamente:
            // un hook que no acaba deja el proceso colgado.
            if (!trabajoTerminado.await(10, TimeUnit.SECONDS)) {
                System.err.println("El trabajo no terminó a tiempo; saliendo de todos modos.");
            }
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    /** Los bucles largos consultan esto en cada iteración. */
    public boolean cancelado() { return cancelado.get(); }

    public void trabajoCompletado() { trabajoTerminado.countDown(); }
}

@Override
public Integer call() {
    try {
        for (RegistroImportacion registro : registros) {
            if (cancelacion.cancelado()) {
                salida.aviso("Importación cancelada por el usuario. "
                           + "Procesados %d de %d registros.".formatted(procesados, registros.size()));
                return CodigoSalida.INTERRUMPIDO;      // 130, convenio POSIX
            }
            importador.importar(registro, enriquecer);
            procesados++;
        }
        return CodigoSalida.OK;
    } finally {
        cancelacion.trabajoCompletado();     // libera el hook
    }
}

public final class Ansi {
    public static final String RESET   = "";
    public static final String ROJO    = "";
    public static final String VERDE   = "";
    public static final String AMARILLO= "";
    public static final String GRIS    = "";
    public static final String NEGRITA = "";
}

$ bibliotech catalogo listar > salida.txt
$ cat salida.txt
^[[32m978-0000000001^[[0m  Java Efectivo …

public class DetectorColor {

    public static boolean debeUsarColor(boolean opcionSinColor) {
        // 1. La opción explícita del usuario manda
        if (opcionSinColor) return false;

        // 2. NO_COLOR: convenio universal (no-color.org). Si existe, con cualquier valor, se respeta
        if (System.getenv("NO_COLOR") != null) return false;

        // 3. FORCE_COLOR: para forzar colores en un pipeline de CI que sí los renderiza
        if (System.getenv("FORCE_COLOR") != null) return true;

        // 4. Terminal "tonto" (algunos entornos de CI, Emacs shell)
        String term = System.getenv("TERM");
        if ("dumb".equals(term)) return false;

        // 5. Sin terminal (tubería o redirección): sin color
        return System.console() != null;
    }
}

Error: no se puede prestar "Java Efectivo" a Diego Alonso.

  Causa:      el empleado ya tiene 3 préstamos activos (máximo permitido: 3).
  Sugerencia: consulta sus préstamos con
              bibliotech prestamo listar --empleado=2
              y devuelve alguno antes de crear uno nuevo.

  Detalle técnico registrado con id: a7f3e91c

public class ManejadorErroresCli implements CommandLine.IExecutionExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(ManejadorErroresCli.class);

    @Override
    public int handleExecutionException(Exception e, CommandLine cl, CommandLine.ParseResult parseo) {

        String idIncidencia = UUID.randomUUID().toString().substring(0, 8);
        // El detalle técnico COMPLETO va al log, no a la pantalla del usuario (06-07)
        log.error("Error en la ejecución del comando [id={}]", idIncidencia, e);

        PrintWriter err = cl.getErr();

        return switch (e) {
            case MaterialNoEncontradoException ex -> {
                err.println(rojo("Error: ") + "no existe ningún material con ISBN " + ex.getIsbn() + ".");
                err.println("  Sugerencia: búscalo con 'bibliotech catalogo buscar --titulo=\"...\"'");
                yield CodigoSalida.NO_ENCONTRADO;
            }
            case LimiteDePrestamosExcedidoException ex -> {
                err.println(rojo("Error: ") + "el empleado " + ex.getNombre()
                          + " ya tiene " + ex.getMaximo() + " préstamos activos.");
                err.println("  Sugerencia: 'bibliotech prestamo listar --empleado=" + ex.getId() + "'");
                yield CodigoSalida.CONFLICTO;
            }
            case ServicioExternoNoDisponibleException ex -> {
                err.println(rojo("Error: ") + "el servicio de metadatos no responde.");
                err.println("  Sugerencia: reintenta más tarde, o usa --sin-enriquecer.");
                yield CodigoSalida.NO_DISPONIBLE;      // 7: el script SÍ debe reintentar
            }
            case BiblioTechException ex -> {
                err.println(rojo("Error: ") + ex.getMessage());
                yield CodigoSalida.ERROR;
            }
            default -> {
                // Lo inesperado: mensaje genérico + identificador para correlacionar con el log
                err.println(rojo("Error inesperado. ") + "Incidencia " + idIncidencia + ".");
                err.println("  Ejecuta con -vv para ver el detalle, o envía ese identificador a soporte.");
                yield CodigoSalida.ERROR;
            }
        };
    }
}

<build>
  <finalName>bibliotech-cli</finalName>
  <plugins>
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
      <configuration>
        <mainClass>com.nexussoftware.bibliotech.consola.BiblioTechCli</mainClass>
        <executable>true</executable>   <!-- añade un script de arranque al propio jar -->
      </configuration>
      <executions>
        <execution><goals><goal>repackage</goal></goals></execution>
      </executions>
    </plugin>
  </plugins>
</build>

./mvnw -pl bibliotech-consola clean package
java -jar bibliotech-consola/target/bibliotech-cli.jar catalogo listar

#!/usr/bin/env bash
# scripts/bibliotech — instálalo en /usr/local/bin/bibliotech
set -euo pipefail

BIBLIOTECH_HOME="${BIBLIOTECH_HOME:-/opt/bibliotech}"
JAVA_BIN="${JAVA_HOME:+$JAVA_HOME/bin/java}"
JAVA_BIN="${JAVA_BIN:-java}"

# Opciones de JVM pensadas para arranque rápido, no para un servidor de larga vida:
#  -XX:TieredStopAtLevel=1  no compilar a fondo: el proceso dura segundos
#  -XX:+UseSerialGC         el GC más barato de inicializar
#  -Xshare:auto             usar el archivo de clases compartidas
exec "$JAVA_BIN" \
  -XX:TieredStopAtLevel=1 \
  -XX:+UseSerialGC \
  -Xshare:auto \
  -Dfile.encoding=UTF-8 \
  ${BIBLIOTECH_OPTS:-} \
  -jar "$BIBLIOTECH_HOME/bibliotech-cli.jar" "$@"      # "$@" preserva los argumentos con espacios

jpackage --type deb \
  --name bibliotech \
  --input bibliotech-consola/target \
  --main-jar bibliotech-cli.jar \
  --main-class org.springframework.boot.loader.launch.JarLauncher \
  --app-version 1.0.0 \
  --vendor "Nexus Software"

./mvnw -pl bibliotech-consola -Pnative native:compile
./bibliotech-consola/target/bibliotech catalogo listar     # arranca en ~50 ms

@ExtendWith(MockitoExtension.class)
class ComandoPrestamoCrearTest {

    @Mock GestionarPrestamos gestor;
    @Mock Salida salida;
    @InjectMocks ComandoPrestamoCrear comando;

    @Test
    void devuelveOkYAvisaCuandoElPrestamoSeCrea() {
        var prestamo = unPrestamoDe("978-0000000001", "Marta Ruiz");
        when(gestor.prestar(any(), eq(1L), isNull())).thenReturn(prestamo);
        ReflectionTestUtils.setField(comando, "isbn", Isbn.de("978-0000000001"));
        ReflectionTestUtils.setField(comando, "idEmpleado", 1L);

        Integer codigo = comando.call();

        assertThat(codigo).isEqualTo(CodigoSalida.OK);
        verify(salida).exito(contains("Préstamo #" + prestamo.getId()));
    }
}

class ParseoArgumentosTest {

    @Test
    void parseaLasOpcionesDelComandoListar() {
        var comando = new ComandoCatalogoListar(mock(ConsultarCatalogo.class), mock(Salida.class));
        var cl = new CommandLine(comando);

        cl.parseArgs("--tipo=LIBRO", "--disponibles", "--limite=10");

        assertThat(ReflectionTestUtils.getField(comando, "tipo")).isEqualTo(TipoMaterial.LIBRO);
        assertThat(ReflectionTestUtils.getField(comando, "soloDisponibles")).isEqualTo(true);
        assertThat(ReflectionTestUtils.getField(comando, "limite")).isEqualTo(10);
    }

    @Test
    void rechazaUnIsbnInvalidoConMensajeUtil() {
        var cl = new CommandLine(new ComandoPrestamoCrear(mock(…), mock(…)));

        assertThatThrownBy(() -> cl.parseArgs("--isbn=1234", "--empleado=1"))
            .isInstanceOf(CommandLine.ParameterException.class)
            .hasMessageContaining("no es un ISBN-13 válido");
    }

    @Test
    void exigeLasOpcionesObligatorias() {
        var cl = new CommandLine(new ComandoPrestamoCrear(mock(…), mock(…)));

        assertThatThrownBy(() -> cl.parseArgs("--empleado=1"))
            .isInstanceOf(CommandLine.MissingParameterException.class)
            .hasMessageContaining("--isbn");
    }
}

@SpringBootTest
class BiblioTechCliIT {

    @Autowired ComandoRaiz raiz;
    @Autowired CommandLine.IFactory fabrica;

    @Test
    void listarCatalogoEnJsonProduceJsonValido() throws Exception {
        var salidaCapturada = new StringWriter();
        var errorCapturado = new StringWriter();

        int codigo = new CommandLine(raiz, fabrica)
                .setOut(new PrintWriter(salidaCapturada))     // Picocli permite redirigir
                .setErr(new PrintWriter(errorCapturado))
                .execute("catalogo", "listar", "--formato=json");

        assertThat(codigo).isEqualTo(CodigoSalida.OK);

        // El resultado debe ser JSON VÁLIDO: nada de banners ni mensajes contaminándolo
        JsonNode arbol = new ObjectMapper().readTree(salidaCapturada.toString());
        assertThat(arbol.isArray()).isTrue();
        assertThat(arbol).hasSize(3);
        assertThat(arbol.get(0).get("titulo").asText()).isEqualTo("Java Efectivo");
    }

    @Test
    void devuelveCodigo5CuandoElMaterialNoExiste() {
        int codigo = new CommandLine(raiz, fabrica)
                .setExecutionExceptionHandler(new ManejadorErroresCli())
                .execute("catalogo", "ficha", "978-9999999999");

        assertThat(codigo).isEqualTo(CodigoSalida.NO_ENCONTRADO);
    }

    @Test
    void devuelveCodigo2CuandoFaltaUnaOpcionObligatoria() {
        int codigo = new CommandLine(raiz, fabrica).execute("prestamo", "crear", "--empleado=1");
        assertThat(codigo).isEqualTo(2);      // error de uso, el que Picocli usa por defecto
    }
}

TablaConsola.de(materiales)
    .columna("ISBN", m -> m.getIsbn().valor())
    .columna("TÍTULO", Material::getTitulo, 45)
    .columna("TIPO", m -> m.tipo().name())
    .columnaNumerica("LIBRES", m -> m.unidadesDisponibles())
    .conTotales()
    .imprimir(salida);

@Command(name = "devolver",
    description = "Registra la devolución de un préstamo.",
    footerHeading = "%nEjemplos:%n",
    footer = {
        "  bibliotech prestamo devolver 42",
        "  bibliotech prestamo devolver 42 --fecha=2026-03-15",
        "  bibliotech prestamo devolver 42 --simular --formato=json"
    })
@Component
public class ComandoPrestamoDevolver implements Callable<Integer> {

    private final GestionarPrestamos gestor;
    private final CalculadoraMultas calculadora;
    private final Salida salida;
    private final Clock reloj;

    @Spec CommandLine.Model.CommandSpec spec;

    public ComandoPrestamoDevolver(GestionarPrestamos gestor, CalculadoraMultas calculadora,
                                   Salida salida, Clock reloj) {
        this.gestor = gestor;
        this.calculadora = calculadora;
        this.salida = salida;
        this.reloj = reloj;
    }

    @Parameters(index = "0", paramLabel = "<idPrestamo>",
                description = "Identificador del préstamo a devolver.")
    private Long idPrestamo;

    @Option(names = "--fecha", description = "Fecha de devolución (yyyy-MM-dd). Por defecto, hoy.")
    private LocalDate fecha;

    @Option(names = "--simular",
            description = "Calcula la multa sin registrar la devolución.")
    private boolean simular;

    @Override
    public Integer call() {
        LocalDate hoy = LocalDate.now(reloj);
        LocalDate fechaEfectiva = (fecha != null) ? fecha : hoy;

        // Validación cruzada: ParameterException produce mensaje + uso + código 2
        if (fechaEfectiva.isAfter(hoy)) {
            throw new CommandLine.ParameterException(spec.commandLine(),
                "--fecha (%s) no puede ser posterior a hoy (%s)."
                    .formatted(fechaEfectiva, hoy));
        }

        Prestamo prestamo = gestor.buscar(idPrestamo)
                .orElseThrow(() -> new PrestamoNoEncontradoException(idPrestamo));

        if (prestamo.getFechaDevolucion().isPresent()) {
            // La excepción la traduce ManejadorErroresCli a código 6 (CONFLICTO)
            throw new PrestamoYaDevueltoException(idPrestamo,
                    prestamo.getFechaDevolucion().orElseThrow());
        }

        if (fechaEfectiva.isBefore(prestamo.getFechaPrestamo())) {
            throw new CommandLine.ParameterException(spec.commandLine(),
                "--fecha (%s) es anterior a la fecha del préstamo (%s)."
                    .formatted(fechaEfectiva, prestamo.getFechaPrestamo()));
        }

        if (simular) {
            Dinero multa = calculadora.calcular(prestamo, fechaEfectiva);
            salida.escribirDevolucion(new ResultadoDevolucion(
                    prestamo.getId(), prestamo.tituloDelMaterial(), prestamo.nombreDelEmpleado(),
                    fechaEfectiva, multa, true));
            salida.aviso("SIMULACIÓN: no se ha registrado nada.");
            return CodigoSalida.OK;
        }

        ResultadoDevolucion resultado = gestor.devolver(idPrestamo, fechaEfectiva);
        salida.escribirDevolucion(resultado);

        if (resultado.multa().esPositiva()) {
            salida.exito("Devolución registrada. Multa: %s (%d días de retraso)."
                    .formatted(resultado.multa(), resultado.diasDeRetraso()));
        } else {
            salida.exito("Devolución registrada en plazo. Sin multa.");
        }
        return CodigoSalida.OK;
    }
}

public void escribirDevolucion(ResultadoDevolucion r) {
    switch (formato) {
        case TABLA -> {
            out.printf("%-14s %s%n", "Préstamo:", "#" + r.idPrestamo());
            out.printf("%-14s %s%n", "Material:", r.tituloMaterial());
            out.printf("%-14s %s%n", "Empleado:", r.nombreEmpleado());
            out.printf("%-14s %s%n", "Devolución:", r.fecha());
            out.printf("%-14s %s%n", "Multa:",
                    r.multa().esPositiva() ? rojo(r.multa().toString()) : verde("sin multa"));
        }
        case CSV -> {
            if (mostrarDecoracion()) out.println("id;material;empleado;fecha;multa");
            out.printf("%d;%s;%s;%s;%s%n", r.idPrestamo(), escapar(r.tituloMaterial()),
                    escapar(r.nombreEmpleado()), r.fecha(), r.multa().importe());
        }
        case JSON -> json(r);
    }
}

$ bibliotech prestamo devolver 42;              echo $?   # 0
$ bibliotech prestamo devolver 9999;            echo $?   # 5 (no encontrado)
$ bibliotech prestamo devolver 42;              echo $?   # 6 (ya devuelto)
$ bibliotech prestamo devolver 42 --fecha=2099-01-01; echo $?   # 2 (uso incorrecto)

@Command(name = "enviar",
    description = "Envía avisos de vencimiento próximo a los empleados afectados.",
    footerHeading = "%nCódigos de salida:%n",
    footer = {
        "  0  todos los avisos se enviaron",
        "  3  no había ningún aviso que enviar",
        "  4  algunos avisos fallaron",
        "  7  el servidor de correo no responde"
    })
@Component
public class ComandoAvisosEnviar implements Callable<Integer> {

    private final ServicioAvisos avisos;
    private final RepositorioPrestamos prestamos;
    private final Salida salida;
    private final GestorCancelacion cancelacion;
    private final Clock reloj;

    @Option(names = "--dias-antelacion", defaultValue = "3",
            description = "Avisar de los vencimientos en N días. Por defecto: ${DEFAULT-VALUE}")
    private int diasAntelacion;

    @Option(names = "--desde-stdin",
            description = "Lee identificadores de empleado de la entrada estándar, uno por línea.")
    private boolean desdeStdin;

    @Option(names = "--simular", description = "Muestra a quién se avisaría, sin enviar nada.")
    private boolean simular;

    @Override
    public Integer call() throws IOException {
        List<Prestamo> objetivo = seleccionarPrestamos();

        if (objetivo.isEmpty()) {
            salida.info("No hay ningún préstamo que requiera aviso.");
            return CodigoSalida.SIN_RESULTADOS;          // 3: NO es un error
        }

        salida.info("Preparando %d avisos%s…".formatted(objetivo.size(), simular ? " (SIMULACIÓN)" : ""));

        var progreso = new BarraProgreso(objetivo.size(), salida);   // se autodesactiva sin terminal
        int enviados = 0;
        List<FalloEnvio> fallos = new ArrayList<>();

        for (Prestamo p : objetivo) {
            if (cancelacion.cancelado()) {
                progreso.terminar();
                salida.aviso("Cancelado. Enviados %d de %d.".formatted(enviados, objetivo.size()));
                return CodigoSalida.INTERRUMPIDO;
            }
            try {
                if (simular) {
                    // El resultado de la simulación SÍ es resultado: va a stdout
                    salida.resultado("%s <%s> — \"%s\" vence el %s"
                            .formatted(p.nombreDelEmpleado(), p.correoDelEmpleado(),
                                       p.tituloDelMaterial(), p.getFechaVencimiento()));
                } else {
                    avisos.enviar(Aviso.porVencimiento(p));
                }
                enviados++;
            } catch (ServicioExternoNoDisponibleException e) {
                // El servidor de correo caído afecta a TODOS: no tiene sentido seguir
                progreso.terminar();
                throw e;                                  // el manejador lo traduce a 7
            } catch (BiblioTechException e) {
                fallos.add(new FalloEnvio(p.getId(), p.correoDelEmpleado(), e.getMessage()));
            } finally {
                progreso.avanzar();
            }
        }
        progreso.terminar();

        if (!fallos.isEmpty()) {
            salida.aviso("%d avisos fallaron:".formatted(fallos.size()));
            fallos.forEach(f -> salida.aviso("  préstamo #%d (%s): %s"
                    .formatted(f.idPrestamo(), f.destino(), f.motivo())));
            salida.info("Enviados %d de %d.".formatted(enviados, objetivo.size()));
            return CodigoSalida.PARCIAL;                  // 4
        }

        salida.exito("Enviados %d avisos.".formatted(enviados));
        return CodigoSalida.OK;
    }

    private List<Prestamo> seleccionarPrestamos() throws IOException {
        LocalDate limite = LocalDate.now(reloj).plusDays(diasAntelacion);

        if (!desdeStdin) {
            return prestamos.activosQueVencenAntesDe(limite);
        }

        List<Long> ids = leerIdsDeStdin();
        if (ids.isEmpty()) {
            salida.aviso("No se leyó ningún identificador de la entrada estándar.");
            return List.of();
        }
        salida.detalle("Filtrando por %d empleados leídos de stdin".formatted(ids.size()));
        return prestamos.activosQueVencenAntesDe(limite).stream()
                .filter(p -> ids.contains(p.getIdEmpleado()))
                .toList();
    }

    private List<Long> leerIdsDeStdin() throws IOException {
        try (var lector = new BufferedReader(new InputStreamReader(System.in, UTF_8))) {
            return lector.lines()
                    .map(String::strip)
                    .filter(l -> !l.isEmpty() && !l.startsWith("#"))
                    .map(l -> {
                        try {
                            return Long.parseLong(l);
                        } catch (NumberFormatException e) {
                            salida.aviso("Se ignora la línea no numérica: '%s'".formatted(l));
                            return null;
                        }
                    })
                    .filter(Objects::nonNull)
                    .distinct()
                    .toList();
        }
    }
}

# Todos los vencimientos de los próximos 3 días
bibliotech avisos enviar

# Solo a los empleados del departamento de Arquitectura
bibliotech empleado listar --departamento=Arquitectura --formato=csv \
  | cut -d';' -f1 | tail -n +2 \
  | bibliotech avisos enviar --desde-stdin --dias-antelacion=7

# Ver a quién se avisaría, sin enviar nada
bibliotech avisos enviar --simular --formato=json | jq -r '.[].correo'

#!/usr/bin/env bash
# /opt/bibliotech/scripts/avisos-diarios.sh
# Ejecutar con: 0 8 * * * /opt/bibliotech/scripts/avisos-diarios.sh
set -uo pipefail                    # sin -e: queremos gestionar los códigos nosotros

LOG="/var/log/bibliotech/avisos-$(date +%F).log"
MAX_INTENTOS=3

for intento in $(seq 1 $MAX_INTENTOS); do
  # El resultado al log; los diagnósticos también, pero separables por si acaso
  bibliotech avisos enviar --dias-antelacion=3 --silencioso >>"$LOG" 2>&1
  codigo=$?

  case $codigo in
    0) echo "$(date -Is) OK: avisos enviados" >>"$LOG"; exit 0 ;;
    3) echo "$(date -Is) Nada que enviar hoy"  >>"$LOG"; exit 0 ;;   # NO es un fallo
    4) echo "$(date -Is) AVISO: envío parcial; revisa el log" >>"$LOG"
       mail -s "BiblioTech: avisos parciales" [email protected] <"$LOG"
       exit 0 ;;
    7) echo "$(date -Is) Correo no disponible; reintento $intento de $MAX_INTENTOS" >>"$LOG"
       sleep $((intento * 120)) ;;                                   # 2, 4, 6 minutos
    *) echo "$(date -Is) ERROR irrecuperable (código $codigo)" >>"$LOG"
       mail -s "BiblioTech: fallo en avisos" [email protected] <"$LOG"
       exit "$codigo" ;;
  esac
done

echo "$(date -Is) ERROR: agotados los reintentos" >>"$LOG"
mail -s "BiblioTech: correo caído tras 3 intentos" [email protected] <"$LOG"
exit 7

/**
 * Formateador de tablas para consola, con anchos automáticos.
 * Uso:
 *   TablaConsola.de(materiales)
 *       .columna("ISBN", m -> m.getIsbn().valor())
 *       .columna("TÍTULO", Material::getTitulo, 45)
 *       .columnaNumerica("LIBRES", Material::unidadesDisponibles)
 *       .conTotales()
 *       .imprimir(salida);
 */
public class TablaConsola<T> {

    private static final int ANCHO_TERMINAL_POR_DEFECTO = 120;
    private static final String SEPARADOR = "  ";

    private final List<T> filas;
    private final List<Columna<T>> columnas = new ArrayList<>();
    private boolean totales = false;

    private TablaConsola(List<T> filas) { this.filas = filas; }

    public static <T> TablaConsola<T> de(List<T> filas) { return new TablaConsola<>(filas); }

    // --- Definición de columnas ---

    public TablaConsola<T> columna(String titulo, Function<T, String> extractor) {
        return columna(titulo, extractor, Integer.MAX_VALUE);
    }

    public TablaConsola<T> columna(String titulo, Function<T, String> extractor, int anchoMaximo) {
        columnas.add(new Columna<>(titulo, extractor, Alineacion.IZQUIERDA, anchoMaximo, null));
        return this;
    }

    public TablaConsola<T> columnaNumerica(String titulo, ToLongFunction<T> extractor) {
        columnas.add(new Columna<>(titulo,
                t -> String.valueOf(extractor.applyAsLong(t)),
                Alineacion.DERECHA, 15, extractor));
        return this;
    }

    public TablaConsola<T> conTotales() { this.totales = true; return this; }

    // --- Impresión ---

    public void imprimir(Salida salida) {
        if (columnas.isEmpty()) throw new IllegalStateException("Define al menos una columna");

        int[] anchos = calcularAnchos();
        ajustarAlTerminal(anchos);

        PrintStream out = salida.out();

        if (salida.mostrarDecoracion()) {
            out.println(fila(anchos, i -> columnas.get(i).titulo()));
            out.println("-".repeat(anchoTotal(anchos)));
        }

        for (T elemento : filas) {
            out.println(fila(anchos, i -> valor(columnas.get(i), elemento, anchos[i])));
        }

        if (totales && salida.mostrarDecoracion()) {
            out.println("-".repeat(anchoTotal(anchos)));
            out.println(fila(anchos, this::totalDeColumna));
            out.printf("%d filas%n", filas.size());
        }
    }

    // --- Cálculo de anchos ---

    private int[] calcularAnchos() {
        int[] anchos = new int[columnas.size()];
        for (int i = 0; i < columnas.size(); i++) {
            Columna<T> c = columnas.get(i);
            int anchoContenido = filas.stream()
                    .map(c.extractor())
                    .mapToInt(String::length)
                    .max().orElse(0);
            // El ancho es el mayor entre el título y el contenido, limitado por el máximo
            anchos[i] = Math.min(c.anchoMaximo(), Math.max(c.titulo().length(), anchoContenido));
        }
        return anchos;
    }

    /**
     * Si la tabla no cabe, recorta proporcionalmente las columnas de texto
     * más anchas, respetando un mínimo de 8 caracteres.
     */
    private void ajustarAlTerminal(int[] anchos) {
        int disponible = anchoTerminal();
        int total = anchoTotal(anchos);
        if (total <= disponible) return;

        int exceso = total - disponible;
        // Recortar de mayor a menor hasta absorber el exceso
        List<Integer> candidatas = IntStream.range(0, anchos.length)
                .boxed()
                .filter(i -> columnas.get(i).alineacion() == Alineacion.IZQUIERDA)
                .sorted(Comparator.comparingInt((Integer i) -> anchos[i]).reversed())
                .toList();

        for (int i : candidatas) {
            if (exceso <= 0) break;
            int recortable = Math.max(0, anchos[i] - 8);
            int recorte = Math.min(recortable, exceso);
            anchos[i] -= recorte;
            exceso -= recorte;
        }
    }

    private int anchoTerminal() {
        // COLUMNS la exporta el shell; si no está, usar el valor por defecto
        String columnas = System.getenv("COLUMNS");
        try {
            return columnas != null ? Integer.parseInt(columnas) : ANCHO_TERMINAL_POR_DEFECTO;
        } catch (NumberFormatException e) {
            return ANCHO_TERMINAL_POR_DEFECTO;
        }
    }

    private int anchoTotal(int[] anchos) {
        return Arrays.stream(anchos).sum() + SEPARADOR.length() * (anchos.length - 1);
    }

    // --- Formato de celdas ---

    private String fila(int[] anchos, IntFunction<String> celda) {
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < anchos.length; i++) {
            if (i > 0) sb.append(SEPARADOR);
            String texto = recortar(celda.apply(i), anchos[i]);
            sb.append(columnas.get(i).alineacion() == Alineacion.DERECHA
                    ? " ".repeat(anchos[i] - texto.length()) + texto
                    : texto + " ".repeat(anchos[i] - texto.length()));
        }
        return sb.toString().stripTrailing();     // sin espacios al final: ensucian al copiar
    }

    private String valor(Columna<T> c, T elemento, int ancho) {
        return recortar(c.extractor().apply(elemento), ancho);
    }

    private static String recortar(String texto, int max) {
        if (texto == null) return "";
        return texto.length() <= max ? texto : texto.substring(0, Math.max(0, max - 1)) + "…";
    }

    private String totalDeColumna(int i) {
        Columna<T> c = columnas.get(i);
        if (c.sumador() == null) return i == 0 ? "TOTAL" : "";
        long suma = filas.stream().mapToLong(c.sumador()).sum();
        return String.valueOf(suma);
    }

    // --- Tipos auxiliares ---

    private enum Alineacion { IZQUIERDA, DERECHA }

    private record Columna<T>(String titulo,
                              Function<T, String> extractor,
                              Alineacion alineacion,
                              int anchoMaximo,
                              ToLongFunction<T> sumador) { }
}

TablaConsola.de(materiales)
    .columna("ISBN", m -> m.getIsbn().valor())
    .columna("TÍTULO", Material::getTitulo, 45)
    .columna("TIPO", m -> m.tipo().name())
    .columnaNumerica("LIBRES", Material::unidadesDisponibles)
    .conTotales()
    .imprimir(salida);

ISBN            TÍTULO                          TIPO     LIBRES
---------------------------------------------------------------
978-0000000001  Java Efectivo                   LIBRO         2
978-0000000002  Patrones de Diseño              LIBRO         0
978-0000000003  Refactorización                 LIBRO         1
---------------------------------------------------------------
TOTAL                                                         3
3 filas