bibliotech cataleg llistar --format=csv | grep "Java" | wc -l
cat isbns.txt | bibliotech cataleg importar --des-de-stdin
bibliotech informe multes --format=json | jq '.[] | select(.quantitat > 10)'

Error: NullPointerException

Error: no s'ha trobat cap material amb ISBN 978-0000000009.

  Causa:       l'ISBN no existeix al cataleg.
  Suggeriment: comprova l'ISBN amb 'bibliotech cataleg cercar --titol="..."'
               o importa'l amb 'bibliotech cataleg importar'.

public static void main(String[] args) {
    String format = "taula";
    boolean detallat = false;
    String isbn = null;

    for (int i = 0; i < args.length; i++) {
        switch (args[i]) {
            case "--format" -> format = args[++i];
            case "-v", "--detallat" -> detallat = true;
            case "--isbn" -> isbn = args[++i];
            default -> {
                System.err.println("Opcio desconeguda: " + args[i]);
                System.exit(2);
            }
        }
    }
    // …
}

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

  <dependency>
    <groupId>info.picocli</groupId>
    <artifactId>picocli-spring-boot-starter</artifactId>   <!-- porta picocli + integracio -->
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>           <!-- sense 'web': aixo 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",                          // com s'invoca
    mixinStandardHelpOptions = true,              // afegeix --help i --version de franc
    version = "BiblioTech CLI 1.0.0",
    description = "Eina de gestio de la biblioteca tecnica de Nexus Software.")
public class Exemple implements Callable<Integer> {   // Callable<Integer>: l'int es el codi de sortida

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

    @Option(names = {"-f", "--format"}, defaultValue = "taula",
            description = "Format de sortida: ${COMPLETION-CANDIDATES}. Per defecte: ${DEFAULT-VALUE}")
    private Format format;

    @Override
    public Integer call() {
        System.out.println("Consultant " + isbn + " en format " + format);
        return 0;                                  // 0 = exit
    }

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

$ java -jar exemple.jar --help
Usage: bibliotech [-hV] [-f=<format>] <isbn>
Eina de gestio de la biblioteca tecnica de Nexus Software.
      <isbn>          ISBN del material a consultar.
  -f, --format=<format>
                      Format de sortida: TAULA, CSV, JSON. Per defecte: TAULA
  -h, --help          Show this help message and exit.
  -V, --version       Print version information and exit.

@Command(name = "prestec")
class OpcionsExemple {

    // Booleana: la seva sola presencia la posa a true
    @Option(names = {"-v", "--detallat"}, description = "Mostra el detall de l'execucio.")
    boolean detallat;

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

    // Amb valor per defecte
    @Option(names = "--dies", defaultValue = "15", description = "Durada en dies.")
    int dies;

    // Tipus de java.time: conversio automatica des d'ISO-8601
    @Option(names = "--des-de", description = "Data d'inici (yyyy-MM-dd).")
    LocalDate desDe;

    // Enum: Picocli valida els valors permesos i els llista a l'ajuda
    @Option(names = "--format", defaultValue = "TAULA")
    Format format;

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

    // Amb aritat: exactament dos valors
    @Option(names = "--rang", arity = "2", paramLabel = "<des-de> <fins-a>")
    int[] rang;

    // Mapa: --propietat clau=valor
    @Option(names = "-D", description = "Propietat addicional.")
    Map<String, String> propietats = new LinkedHashMap<>();

    // Sensible: Picocli la demana per teclat sense mostrar-la si no es passa
    @Option(names = "--clau", interactive = true, arity = "0..1")
    char[] clau;

    // Posicionals: tots els restants
    @Parameters(index = "0", description = "Fitxer d'entrada.")
    Path fitxer;

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

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

@ArgGroup(exclusive = true, multiplicity = "1")   // exactament un dels tres
OrigenDades origen;

/** Converteix el text de la linia d'ordres en l'objecte de valor del domini. */
public class ConversorIsbn implements CommandLine.ITypeConverter<Isbn> {

    @Override
    public Isbn convert(String valor) {
        try {
            return Isbn.de(valor);          // l'objecte de valor ja valida (12-02)
        } catch (IsbnInvalidException e) {
            // TypeConversionException produeix un missatge d'us, no una traca
            throw new CommandLine.TypeConversionException(
                "'" + valor + "' no es un ISBN-13 valid. Format esperat: 978-XXXXXXXXXX");
        }
    }
}

@Option(names = "--isbn", required = true, converter = ConversorIsbn.class)
private Isbn isbn;      // el camp es del tipus del domini, no String!

$ bibliotech prestec crear --isbn=1234 --empleat=1
Invalid value for option '--isbn': '1234' no es un ISBN-13 valid.
Format esperat: 978-XXXXXXXXXX
Usage: bibliotech prestec crear [-hV] --empleat=<id> --isbn=<isbn> [--dies=<n>]
…

@Spec CommandLine.Model.CommandSpec spec;

private void validar() {
    if (desDe != null && finsA != null && desDe.isAfter(finsA)) {
        throw new CommandLine.ParameterException(spec.commandLine(),
            "--des-de (" + desDe + ") no pot ser posterior a --fins-a (" + finsA + ")");
    }
}

@Command(
    name = "bibliotech",
    mixinStandardHelpOptions = true,
    version = "BiblioTech CLI 1.0.0",
    description = "Gestio de la biblioteca tecnica de Nexus Software.",
    subcommands = {
        OrdreCataleg.class,
        OrdrePrestec.class,
        OrdreAvisos.class,
        OrdreInforme.class,
        CommandLine.HelpCommand.class          // 'bibliotech help cataleg'
    })
@Component
public class OrdreArrel implements Callable<Integer> {

    @Override
    public Integer call() {
        // Sense subordre, mostrar l'ajuda i retornar error d'us:
        // aixi un script sap que la invocacio estava incompleta.
        CommandLine.usage(this, System.out);
        return CodiSortida.ERROR_US;
    }
}

@Command(name = "cataleg",
         description = "Operacions sobre el cataleg de materials.",
         subcommands = {OrdreCatalegLlistar.class, OrdreCatalegCercar.class,
                        OrdreCatalegImportar.class, OrdreCatalegFitxa.class})
@Component
public class OrdreCataleg implements Callable<Integer> {
    @Override public Integer call() {
        CommandLine.usage(this, System.out);
        return CodiSortida.ERROR_US;
    }
}

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

    @Option(names = {"-f", "--format"}, scope = CommandLine.ScopeType.INHERIT,
            defaultValue = "TAULA", description = "Format de sortida: ${COMPLETION-CANDIDATES}")
    Format format;

    @Option(names = {"-q", "--silencios"}, scope = CommandLine.ScopeType.INHERIT,
            description = "Nomes errors.")
    boolean silencios;

    @Option(names = {"-v", "--detallat"}, scope = CommandLine.ScopeType.INHERIT,
            description = "Detall de l'execucio.")
    boolean detallat;
}

@Command(name = "importar",
    description = "Importa materials al cataleg des d'un fitxer o des de l'entrada estandard.",
    footerHeading = "%nExemples:%n",
    footer = {
        "  bibliotech cataleg importar cataleg.csv",
        "  bibliotech cataleg importar --format-entrada=json dades.json --simular",
        "  cat isbns.txt | bibliotech cataleg importar --des-de-stdin --enriquir",
        "",
        "Codis de sortida: 0 correcte, 1 error, 2 us incorrecte, 4 importacio parcial."
    })
class OrdreCatalegImportar implements Callable<Integer> { … }

# Generar l'script (una vegada, en la construccio)
java -cp bibliotech-consola.jar picocli.AutoComplete \
     -n bibliotech com.nexussoftware.bibliotech.consola.OrdreArrel

# Activar-lo a la sessio
source bibliotech_completion

# Ara funciona el tabulador
$ bibliotech cat<TAB>          → bibliotech cataleg
$ bibliotech cataleg <TAB>     → cercar  fitxa  importar  llistar
$ bibliotech cataleg llistar --format=<TAB>  → TAULA  CSV  JSON

package com.nexussoftware.bibliotech.consola;

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

    private final OrdreArrel ordreArrel;
    private final CommandLine.IFactory fabrica;    // l'aporta l'starter de Picocli
    private int codiSortida;

    public BiblioTechCli(OrdreArrel ordreArrel, CommandLine.IFactory fabrica) {
        this.ordreArrel = ordreArrel;
        this.fabrica = fabrica;
    }

    @Override
    public void run(String... args) {
        this.codiSortida = new CommandLine(ordreArrel, fabrica)
                .setCaseInsensitiveEnumValuesAllowed(true)     // --format=json i JSON
                .setExecutionExceptionHandler(new GestorErrorsCli())
                .execute(args);
    }

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

    public static void main(String[] args) {
        // SpringApplication.exit retorna el codi de l'ExitCodeGenerator,
        // i tanca el context ordenadament abans de sortir.
        System.exit(SpringApplication.exit(SpringApplication.run(BiblioTechCli.class, args)));
    }
}

@Command(name = "crear", description = "Crea un prestec d'un material a un empleat.")
@Component
public class OrdrePrestecCrear implements Callable<Integer> {

    private final GestionarPrestecs gestor;      // injeccio per constructor, com sempre!
    private final Sortida sortida;

    public OrdrePrestecCrear(GestionarPrestecs gestor, Sortida sortida) {
        this.gestor = gestor;
        this.sortida = sortida;
    }

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

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

    @Option(names = "--dies", description = "Durada. Per defecte, la del tipus de material.")
    private Integer dies;

    @Override
    public Integer call() {
        Prestec prestec = gestor.prestar(isbn, idEmpleat, dies);
        sortida.correcte("Prestec #%d creat. Venc el %s."
                .formatted(prestec.getId(), prestec.getDataVenciment()));
        return CodiSortida.OK;
    }
}

spring:
  main:
    web-application-type: none      # sense Tomcat
    banner-mode: off                # sense baner ASCII contaminant la sortida
  output:
    ansi:
      enabled: detect               # colors nomes si el terminal els admet

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

@Command(name = "llistar",
    description = "Llista els materials del cataleg.",
    footerHeading = "%nExemples:%n",
    footer = {
        "  bibliotech cataleg llistar --tipus=LLIBRE --disponibles",
        "  bibliotech cataleg llistar --format=csv > cataleg.csv",
        "  bibliotech cataleg llistar --format=json | jq '.[].titol'"
    })
@Component
public class OrdreCatalegLlistar implements Callable<Integer> {

    private final ConsultarCataleg cataleg;
    private final Sortida sortida;

    public OrdreCatalegLlistar(ConsultarCataleg cataleg, Sortida sortida) {
        this.cataleg = cataleg;
        this.sortida = sortida;
    }

    @Option(names = "--tipus", description = "Filtrar per tipus: ${COMPLETION-CANDIDATES}")
    private TipusMaterial tipus;

    @Option(names = "--disponibles", description = "Nomes materials amb unitats lliures.")
    private boolean nomesDisponibles;

    @Option(names = "--limit", defaultValue = "50",
            description = "Nombre maxim de resultats. Per defecte: ${DEFAULT-VALUE}")
    private int limit;

    @Option(names = "--ordenar-per", defaultValue = "TITOL",
            description = "Criteri d'ordre: ${COMPLETION-CANDIDATES}")
    private CriteriOrdre ordre;

    @Override
    public Integer call() {
        var criteri = CriteriCerca.builder()               // Builder de 12-02
                .tipus(tipus)
                .nomesDisponibles(nomesDisponibles)
                .construir();

        List<Material> resultats = cataleg.cercar(criteri, ordre, limit);

        if (resultats.isEmpty()) {
            sortida.avis("No s'ha trobat cap material amb aquests criteris.");
            return CodiSortida.SENSE_RESULTATS;            // 3: diferent d'error
        }

        sortida.escriureMaterials(resultats);              // el format el decideix Sortida
        sortida.info("%d materials.".formatted(resultats.size()));
        return CodiSortida.OK;
    }
}

@Command(name = "shell", description = "Mode interactiu. Escriu 'sortir' per acabar.")
@Component
public class OrdreShell implements Callable<Integer> {

    private final OrdreArrel arrel;
    private final CommandLine.IFactory fabrica;

    @Override
    public Integer call() {
        // Console es null si l'entrada esta redirigida: llavors el shell no te sentit
        Console consola = System.console();
        if (consola == null) {
            System.err.println("El mode interactiu requereix un terminal.");
            return CodiSortida.ERROR_US;
        }

        System.out.println("BiblioTech 1.0.0 — escriu 'ajuda' o 'sortir'.");
        CommandLine cl = new CommandLine(arrel, fabrica);

        while (true) {
            String linia = consola.readLine("bibliotech> ");
            if (linia == null || linia.isBlank()) continue;
            if (linia.equals("sortir") || linia.equals("exit")) return CodiSortida.OK;
            if (linia.equals("ajuda")) { cl.usage(System.out); continue; }

            // Reutilitza EXACTAMENT la mateixa analisi i les mateixes ordres
            cl.execute(trossejar(linia));
        }
    }

    /** Trosseja respectant les cometes: cercar --titol="Java Eficac" */
    private String[] trossejar(String linia) {
        List<String> parts = new ArrayList<>();
        Matcher m = Pattern.compile("\"([^\"]*)\"|(\\S+)").matcher(linia);
        while (m.find()) {
            parts.add(m.group(1) != null ? m.group(1) : m.group(2));
        }
        return parts.toArray(String[]::new);
    }
}

@Option(names = "--des-de-stdin", description = "Llegeix els ISBN de l'entrada estandard, un per linia.")
private boolean desDeStdin;

@Parameters(index = "0", arity = "0..1", description = "Fitxer d'entrada.")
private Path fitxer;

private List<String> llegirEntrada() throws IOException {
    if (desDeStdin) {
        // Compte amb la codificacio: en Java 18+ el defecte es UTF-8, pero ser explicit no fa mal
        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 comentaris
                    .toList();
        }
    }
    if (fitxer != null) {
        return Files.readAllLines(fitxer, StandardCharsets.UTF_8);
    }
    throw new CommandLine.ParameterException(spec.commandLine(),
        "Indica un fitxer d'entrada o fes servir --des-de-stdin.");
}

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

$ bibliotech cataleg llistar                      # terminal: colors, capçaleres, totals
$ bibliotech cataleg llistar > cataleg.txt        # fitxer: sense colors ni adorns
$ bibliotech cataleg llistar | grep Java          # canonada: ídem

# El resultat va al fitxer; els avisos se segueixen veient a la pantalla
bibliotech cataleg importar dades.csv > resultat.json 2> importacio.log

# Encadenar sense que res es contamini
bibliotech informe multes --format=json | jq '[.[] | select(.quantitat > 10)] | length'

# Fer servir la sortida d'una ordre com a entrada d'una altra
bibliotech prestec llistar --vencuts --format=csv | cut -d';' -f2 | \
  bibliotech avisos enviar --des-de-stdin

bibliotech avisos enviar || echo "FALLADA: revisa el log"    # || s'executa si el codi != 0

public final class CodiSortida {
    public static final int OK = 0;
    public static final int ERROR = 1;
    public static final int ERROR_US = 2;
    public static final int SENSE_RESULTATS = 3;
    public static final int PARCIAL = 4;
    public static final int NO_TROBAT = 5;
    public static final int CONFLICTE = 6;
    public static final int NO_DISPONIBLE = 7;
    public static final int INTERROMPUT = 130;

    private CodiSortida() { }
}

#!/usr/bin/env bash
# Reintentar nomes quan te sentit
for intent in 1 2 3; do
  bibliotech cataleg importar --enriquir dades.csv
  codi=$?
  case $codi in
    0) echo "Importacio correcta"; exit 0 ;;
    7) echo "Servei no disponible; reintent $intent"; sleep $((intent * 30)) ;;
    *) echo "Error no recuperable (codi $codi)"; exit $codi ;;
  esac
done
exit 7

@Component
public class Sortida {

    private final ObjectMapper json;         // Jackson, del modul 11: bean unic
    private final PrintStream out;
    private final PrintStream err;

    private Format format = Format.TAULA;
    private Nivell nivell = Nivell.NORMAL;
    private boolean color = true;

    public Sortida(ObjectMapper json) {
        this.json = json;
        // Codificacio explicita: sense aixo, els accents es trenquen en redirigir a 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 escriureMaterials(List<Material> materials) {
        switch (format) {
            case TAULA -> taula(materials);
            case CSV   -> csv(materials);
            case JSON  -> json(materials.stream().map(MaterialDto::desDe).toList());
        }
    }
    // …
}

private void taula(List<Material> materials) {
    // 1. Calcular l'amplada de cada columna: la del contingut mes llarg, amb un maxim
    int ampladaTitol = Math.min(45, Math.max(6,
            materials.stream().mapToInt(m -> m.getTitol().length()).max().orElse(6)));

    String formatFila = "%-17s  %-" + ampladaTitol + "s  %-8s  %5s%n";

    // 2. Capcalera nomes si NO es una canonada i no estem en mode silencios
    if (mostrarDecoracio()) {
        out.printf(formatFila, "ISBN", "TITOL", "TIPUS", "LLIURES");
        out.println("-".repeat(17 + ampladaTitol + 8 + 5 + 6));
    }

    // 3. Files
    for (Material m : materials) {
        out.printf(formatFila,
                m.getIsbn().valor(),
                retallar(m.getTitol(), ampladaTitol),
                m.tipus(),
                acolorirDisponibilitat(m.unitatsDisponibles()));
    }
}

/** Retalla amb punts suspensius per no descompensar la taula. */
private String retallar(String text, int max) {
    return text.length() <= max ? text : text.substring(0, max - 1) + "…";
}

ISBN               TITOL                                 TIPUS     LLIURES
-------------------------------------------------------------------------
978-0000000001     Java Eficac                           LLIBRE          2
978-0000000002     Patrons de Disseny                    LLIBRE          0
978-0000000003     Refactoritzacio                       LLIBRE          1

private void csv(List<Material> materials) {
    if (mostrarDecoracio()) out.println("isbn;titol;tipus;disponibles");
    for (Material m : materials) {
        out.printf("%s;%s;%s;%d%n",
                m.getIsbn().valor(), escapar(m.getTitol()), m.tipus(), m.unitatsDisponibles());
    }
}

private String escapar(String valor) {
    // Si conte separador, cometes o salts de linia, cal encometar i duplicar les cometes
    if (valor.contains(";") || valor.contains("\"") || valor.contains("\n")) {
        return '"' + valor.replace("\"", "\"\"") + '"';
    }
    return valor;
}

private void json(Object valor) {
    try {
        // Sense sagnar si es una canonada (mes compacte); sagnat si ho llegeix una persona
        ObjectWriter escriptor = esTerminal()
                ? json.writerWithDefaultPrettyPrinter()
                : json.writer();
        out.println(escriptor.writeValueAsString(valor));
    } catch (JsonProcessingException e) {
        throw new SortidaFallidaException("No s'ha pogut serialitzar el resultat", e);
    }
}

public enum Nivell { SILENCIOS, NORMAL, DETALLAT, TRACA }

@Component
public class Sortida {

    /** Resultat: SEMPRE a stdout, fins i tot en mode silencios. Es el que ha demanat l'usuari. */
    public void resultat(String text) { out.println(text); }

    /** Informacio contextual: a stderr, per no contaminar la canonada. */
    public void info(String text) {
        if (nivell.ordinal() >= Nivell.NORMAL.ordinal()) err.println(text);
    }

    /** Detall d'execucio: nomes amb -v. */
    public void detall(String text) {
        if (nivell.ordinal() >= Nivell.DETALLAT.ordinal()) err.println(gris("  " + text));
    }

    public void avis(String text)     { err.println(groc("Avis: ") + text); }
    public void error(String text)    { err.println(vermell("Error: ") + text); }
    public void correcte(String text) { if (nivell != Nivell.SILENCIOS) err.println(verd("✓ ") + text); }
}

@Option(names = {"-v", "--detallat"}, scope = ScopeType.INHERIT)
void setDetallat(boolean[] vegades) {
    Nivell nivell = vegades.length >= 2 ? Nivell.TRACA : Nivell.DETALLAT;
    sortida.setNivell(nivell);
    if (nivell == Nivell.TRACA) {
        // Pujar el nivell de Logback en calent (11-07)
        ((ch.qos.logback.classic.Logger) LoggerFactory.getLogger("com.nexussoftware.bibliotech"))
            .setLevel(ch.qos.logback.classic.Level.DEBUG);
    }
}

@Command(name = "importar", description = "Importa materials al cataleg.")
@Component
public class OrdreCatalegImportar implements Callable<Integer> {

    private final ImportadorCataleg importador;
    private final Sortida sortida;

    @Parameters(index = "0", arity = "0..1") private Path fitxer;
    @Option(names = "--des-de-stdin") private boolean desDeStdin;
    @Option(names = "--enriquir", description = "Completa les metadades des de l'API externa.")
    private boolean enriquir;
    @Option(names = "--simular", description = "No escriu res; mostra el que faria.")
    private boolean simular;

    @Override
    public Integer call() throws Exception {
        List<RegistreImportacio> registres = llegirEntrada();
        sortida.info("Important %d registres%s…"
                .formatted(registres.size(), simular ? " (SIMULACIO)" : ""));

        var progres = new BarraProgres(registres.size(), sortida);
        var correctes = new AtomicInteger();                 // modul 8
        var errors = Collections.synchronizedList(new ArrayList<ErrorImportacio>());

        // Fils virtuals: milers de tasques bloquejants d'E/S sense esgotar el sistema
        try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
            for (RegistreImportacio registre : registres) {
                executor.submit(() -> {
                    try {
                        if (!simular) importador.importar(registre, enriquir);
                        correctes.incrementAndGet();
                    } catch (BiblioTechException e) {
                        errors.add(ErrorImportacio.de(registre, e));
                    } finally {
                        progres.avancar();
                    }
                });
            }
        }   // el tancament del try-with-resources espera que TOTES acabin

        progres.acabar();

        sortida.escriureResultatImportacio(correctes.get(), errors);

        if (errors.isEmpty()) return CodiSortida.OK;
        if (correctes.get() == 0) return CodiSortida.ERROR;
        return CodiSortida.PARCIAL;                           // el 4 de la taula
    }
}

public class BarraProgres {

    private static final int AMPLADA = 40;

    private final int total;
    private final Sortida sortida;
    private final AtomicInteger actual = new AtomicInteger();
    private final long inici = System.nanoTime();
    private final boolean activa;
    private volatile long ultimRepintat;

    public BarraProgres(int total, Sortida sortida) {
        this.total = total;
        this.sortida = sortida;
        // DECISIO 1: nomes si hi ha terminal i no estem en silencios.
        // Una barra de progres en un fitxer de log es brossa illegible.
        this.activa = sortida.esTerminal() && sortida.nivell() != Nivell.SILENCIOS;
    }

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

        // DECISIO 2: limitar el repintat. Repintar 5.000 vegades per segon
        // consumeix mes CPU que la feina mateixa.
        long ara = System.nanoTime();
        if (n < total && ara - ultimRepintat < 100_000_000L) return;   // 100 ms
        ultimRepintat = ara;

        pintar(n);
    }

    private void pintar(int n) {
        int plens = (int) ((double) n / total * AMPLADA);
        long segons = (System.nanoTime() - inici) / 1_000_000_000L;
        long restants = n > 0 ? segons * (total - n) / n : 0;

        // DECISIO 3: a stderr, no a stdout. El progres NO es el resultat.
        // \r torna al principi de la linia sense saltar: la barra se sobreescriu.
        sortida.err().printf("\r[%s%s] %d/%d (%d%%) ETA %ds  ",
                "=".repeat(plens), " ".repeat(AMPLADA - plens),
                n, total, n * 100 / total, restants);
    }

    public void acabar() {
        if (activa) sortida.err().println();    // tancar la linia de la barra
    }
}

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

@Component
public class GestorCancellacio {

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

    private final AtomicBoolean cancellat = new AtomicBoolean(false);
    private final CountDownLatch treballAcabat = new CountDownLatch(1);

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

    private void enRebreSenyal() {
        cancellat.set(true);
        System.err.println("\nCancellant… (prem Ctrl+C de nou per forcar)");
        try {
            // Donar un marge per acabar ordenadament, pero NO esperar indefinidament:
            // un hook que no acaba deixa el proces penjat.
            if (!treballAcabat.await(10, TimeUnit.SECONDS)) {
                System.err.println("La feina no ha acabat a temps; surto igualment.");
            }
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    /** Els bucles llargs consulten aixo a cada iteracio. */
    public boolean cancellat() { return cancellat.get(); }

    public void treballCompletat() { treballAcabat.countDown(); }
}

@Override
public Integer call() {
    try {
        for (RegistreImportacio registre : registres) {
            if (cancellacio.cancellat()) {
                sortida.avis("Importacio cancellada per l'usuari. "
                           + "Processats %d de %d registres.".formatted(processats, registres.size()));
                return CodiSortida.INTERROMPUT;        // 130, conveni POSIX
            }
            importador.importar(registre, enriquir);
            processats++;
        }
        return CodiSortida.OK;
    } finally {
        cancellacio.treballCompletat();      // allibera el hook
    }
}

public final class Ansi {
    public static final String RESET   = "[0m";
    public static final String VERMELL = "[31m";
    public static final String VERD    = "[32m";
    public static final String GROC    = "[33m";
    public static final String GRIS    = "[90m";
    public static final String NEGRETA = "[1m";
}

$ bibliotech cataleg llistar > sortida.txt
$ cat sortida.txt
^[[32m978-0000000001^[[0m  Java Eficac …

public class DetectorColor {

    public static boolean calUsarColor(boolean opcioSenseColor) {
        // 1. L'opcio explicita de l'usuari mana
        if (opcioSenseColor) return false;

        // 2. NO_COLOR: conveni universal (no-color.org). Si existeix, amb qualsevol valor, es respecta
        if (System.getenv("NO_COLOR") != null) return false;

        // 3. FORCE_COLOR: per forcar colors en un pipeline de CI que si que els representa
        if (System.getenv("FORCE_COLOR") != null) return true;

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

        // 5. Sense terminal (canonada o redireccio): sense color
        return System.console() != null;
    }
}

Error: no es pot prestar "Java Eficac" a Diego Alonso.

  Causa:       l'empleat ja te 3 prestecs actius (maxim permes: 3).
  Suggeriment: consulta els seus prestecs amb
               bibliotech prestec llistar --empleat=2
               i retorna'n algun abans de crear-ne un de nou.

  Detall tecnic registrat amb id: a7f3e91c

public class GestorErrorsCli implements CommandLine.IExecutionExceptionHandler {

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

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

        String idIncidencia = UUID.randomUUID().toString().substring(0, 8);
        // El detall tecnic COMPLET va al log, no a la pantalla de l'usuari (06-07)
        log.error("Error en l'execucio de l'ordre [id={}]", idIncidencia, e);

        PrintWriter err = cl.getErr();

        return switch (e) {
            case MaterialNoTrobatException ex -> {
                err.println(vermell("Error: ") + "no existeix cap material amb ISBN " + ex.getIsbn() + ".");
                err.println("  Suggeriment: cerca'l amb 'bibliotech cataleg cercar --titol=\"...\"'");
                yield CodiSortida.NO_TROBAT;
            }
            case LimitPrestecsExceditException ex -> {
                err.println(vermell("Error: ") + "l'empleat " + ex.getNom()
                          + " ja te " + ex.getMaxim() + " prestecs actius.");
                err.println("  Suggeriment: 'bibliotech prestec llistar --empleat=" + ex.getId() + "'");
                yield CodiSortida.CONFLICTE;
            }
            case ServeiExternNoDisponibleException ex -> {
                err.println(vermell("Error: ") + "el servei de metadades no respon.");
                err.println("  Suggeriment: reintenta-ho mes tard, o fes servir --sense-enriquir.");
                yield CodiSortida.NO_DISPONIBLE;       // 7: l'script SI que ha de reintentar
            }
            case BiblioTechException ex -> {
                err.println(vermell("Error: ") + ex.getMessage());
                yield CodiSortida.ERROR;
            }
            default -> {
                // L'inesperat: missatge generic + identificador per correlacionar amb el log
                err.println(vermell("Error inesperat. ") + "Incidencia " + idIncidencia + ".");
                err.println("  Executa amb -vv per veure el detall, o envia aquest identificador a suport.");
                yield CodiSortida.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>   <!-- afegeix un script d'arrencada al jar mateix -->
      </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 cataleg llistar

#!/usr/bin/env bash
# scripts/bibliotech — installa'l a /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}"

# Opcions de JVM pensades per a un arrencada rapida, no per a un servidor de vida llarga:
#  -XX:TieredStopAtLevel=1  no compilar a fons: el proces dura segons
#  -XX:+UseSerialGC         el GC mes barat d'inicialitzar
#  -Xshare:auto             fer servir l'arxiu de classes compartides
exec "$JAVA_BIN" \
  -XX:TieredStopAtLevel=1 \
  -XX:+UseSerialGC \
  -Xshare:auto \
  -Dfile.encoding=UTF-8 \
  ${BIBLIOTECH_OPTS:-} \
  -jar "$BIBLIOTECH_HOME/bibliotech-cli.jar" "$@"      # "$@" preserva els arguments amb espais

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 cataleg llistar     # arrenca en ~50 ms

@ExtendWith(MockitoExtension.class)
class OrdrePrestecCrearTest {

    @Mock GestionarPrestecs gestor;
    @Mock Sortida sortida;
    @InjectMocks OrdrePrestecCrear ordre;

    @Test
    void retornaOkIAvisaQuanElPrestecEsCrea() {
        var prestec = unPrestecDe("978-0000000001", "Marta Ruiz");
        when(gestor.prestar(any(), eq(1L), isNull())).thenReturn(prestec);
        ReflectionTestUtils.setField(ordre, "isbn", Isbn.de("978-0000000001"));
        ReflectionTestUtils.setField(ordre, "idEmpleat", 1L);

        Integer codi = ordre.call();

        assertThat(codi).isEqualTo(CodiSortida.OK);
        verify(sortida).correcte(contains("Prestec #" + prestec.getId()));
    }
}

class ParseigArgumentsTest {

    @Test
    void analitzaLesOpcionsDeLordreLlistar() {
        var ordre = new OrdreCatalegLlistar(mock(ConsultarCataleg.class), mock(Sortida.class));
        var cl = new CommandLine(ordre);

        cl.parseArgs("--tipus=LLIBRE", "--disponibles", "--limit=10");

        assertThat(ReflectionTestUtils.getField(ordre, "tipus")).isEqualTo(TipusMaterial.LLIBRE);
        assertThat(ReflectionTestUtils.getField(ordre, "nomesDisponibles")).isEqualTo(true);
        assertThat(ReflectionTestUtils.getField(ordre, "limit")).isEqualTo(10);
    }

    @Test
    void rebutjaUnIsbnInvalidAmbMissatgeUtil() {
        var cl = new CommandLine(new OrdrePrestecCrear(mock(…), mock(…)));

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

    @Test
    void exigeixLesOpcionsObligatories() {
        var cl = new CommandLine(new OrdrePrestecCrear(mock(…), mock(…)));

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

@SpringBootTest
class BiblioTechCliIT {

    @Autowired OrdreArrel arrel;
    @Autowired CommandLine.IFactory fabrica;

    @Test
    void llistarCatalegEnJsonProdueixJsonValid() throws Exception {
        var sortidaCapturada = new StringWriter();
        var errorCapturat = new StringWriter();

        int codi = new CommandLine(arrel, fabrica)
                .setOut(new PrintWriter(sortidaCapturada))    // Picocli permet redirigir
                .setErr(new PrintWriter(errorCapturat))
                .execute("cataleg", "llistar", "--format=json");

        assertThat(codi).isEqualTo(CodiSortida.OK);

        // El resultat ha de ser JSON VALID: res de baners ni missatges contaminant-lo
        JsonNode arbre = new ObjectMapper().readTree(sortidaCapturada.toString());
        assertThat(arbre.isArray()).isTrue();
        assertThat(arbre).hasSize(3);
        assertThat(arbre.get(0).get("titol").asText()).isEqualTo("Java Eficac");
    }

    @Test
    void retornaCodi5QuanElMaterialNoExisteix() {
        int codi = new CommandLine(arrel, fabrica)
                .setExecutionExceptionHandler(new GestorErrorsCli())
                .execute("cataleg", "fitxa", "978-9999999999");

        assertThat(codi).isEqualTo(CodiSortida.NO_TROBAT);
    }

    @Test
    void retornaCodi2QuanFaltaUnaOpcioObligatoria() {
        int codi = new CommandLine(arrel, fabrica).execute("prestec", "crear", "--empleat=1");
        assertThat(codi).isEqualTo(2);        // error d'us, el que Picocli fa servir per defecte
    }
}

TaulaConsola.de(materials)
    .columna("ISBN", m -> m.getIsbn().valor())
    .columna("TITOL", Material::getTitol, 45)
    .columna("TIPUS", m -> m.tipus().name())
    .columnaNumerica("LLIURES", m -> m.unitatsDisponibles())
    .ambTotals()
    .imprimir(sortida);

@Command(name = "retornar",
    description = "Registra la devolucio d'un prestec.",
    footerHeading = "%nExemples:%n",
    footer = {
        "  bibliotech prestec retornar 42",
        "  bibliotech prestec retornar 42 --data=2026-03-15",
        "  bibliotech prestec retornar 42 --simular --format=json"
    })
@Component
public class OrdrePrestecRetornar implements Callable<Integer> {

    private final GestionarPrestecs gestor;
    private final CalculadoraMultes calculadora;
    private final Sortida sortida;
    private final Clock rellotge;

    @Spec CommandLine.Model.CommandSpec spec;

    public OrdrePrestecRetornar(GestionarPrestecs gestor, CalculadoraMultes calculadora,
                                Sortida sortida, Clock rellotge) {
        this.gestor = gestor;
        this.calculadora = calculadora;
        this.sortida = sortida;
        this.rellotge = rellotge;
    }

    @Parameters(index = "0", paramLabel = "<idPrestec>",
                description = "Identificador del prestec a retornar.")
    private Long idPrestec;

    @Option(names = "--data", description = "Data de devolucio (yyyy-MM-dd). Per defecte, avui.")
    private LocalDate data;

    @Option(names = "--simular",
            description = "Calcula la multa sense registrar la devolucio.")
    private boolean simular;

    @Override
    public Integer call() {
        LocalDate avui = LocalDate.now(rellotge);
        LocalDate dataEfectiva = (data != null) ? data : avui;

        // Validacio creuada: ParameterException produeix missatge + us + codi 2
        if (dataEfectiva.isAfter(avui)) {
            throw new CommandLine.ParameterException(spec.commandLine(),
                "--data (%s) no pot ser posterior a avui (%s)."
                    .formatted(dataEfectiva, avui));
        }

        Prestec prestec = gestor.cercar(idPrestec)
                .orElseThrow(() -> new PrestecNoTrobatException(idPrestec));

        if (prestec.getDataDevolucio().isPresent()) {
            // L'excepcio la tradueix GestorErrorsCli a codi 6 (CONFLICTE)
            throw new PrestecJaRetornatException(idPrestec,
                    prestec.getDataDevolucio().orElseThrow());
        }

        if (dataEfectiva.isBefore(prestec.getDataPrestec())) {
            throw new CommandLine.ParameterException(spec.commandLine(),
                "--data (%s) es anterior a la data del prestec (%s)."
                    .formatted(dataEfectiva, prestec.getDataPrestec()));
        }

        if (simular) {
            Diner multa = calculadora.calcular(prestec, dataEfectiva);
            sortida.escriureDevolucio(new ResultatDevolucio(
                    prestec.getId(), prestec.titolDelMaterial(), prestec.nomDeLempleat(),
                    dataEfectiva, multa, true));
            sortida.avis("SIMULACIO: no s'ha registrat res.");
            return CodiSortida.OK;
        }

        ResultatDevolucio resultat = gestor.retornar(idPrestec, dataEfectiva);
        sortida.escriureDevolucio(resultat);

        if (resultat.multa().esPositiva()) {
            sortida.correcte("Devolucio registrada. Multa: %s (%d dies de retard)."
                    .formatted(resultat.multa(), resultat.diesDeRetard()));
        } else {
            sortida.correcte("Devolucio registrada en termini. Sense multa.");
        }
        return CodiSortida.OK;
    }
}

public void escriureDevolucio(ResultatDevolucio r) {
    switch (format) {
        case TAULA -> {
            out.printf("%-14s %s%n", "Prestec:", "#" + r.idPrestec());
            out.printf("%-14s %s%n", "Material:", r.titolMaterial());
            out.printf("%-14s %s%n", "Empleat:", r.nomEmpleat());
            out.printf("%-14s %s%n", "Devolucio:", r.data());
            out.printf("%-14s %s%n", "Multa:",
                    r.multa().esPositiva() ? vermell(r.multa().toString()) : verd("sense multa"));
        }
        case CSV -> {
            if (mostrarDecoracio()) out.println("id;material;empleat;data;multa");
            out.printf("%d;%s;%s;%s;%s%n", r.idPrestec(), escapar(r.titolMaterial()),
                    escapar(r.nomEmpleat()), r.data(), r.multa().quantitat());
        }
        case JSON -> json(r);
    }
}

$ bibliotech prestec retornar 42;              echo $?   # 0
$ bibliotech prestec retornar 9999;            echo $?   # 5 (no trobat)
$ bibliotech prestec retornar 42;              echo $?   # 6 (ja retornat)
$ bibliotech prestec retornar 42 --data=2099-01-01; echo $?   # 2 (us incorrecte)

@Command(name = "enviar",
    description = "Envia avisos de venciment proxim als empleats afectats.",
    footerHeading = "%nCodis de sortida:%n",
    footer = {
        "  0  tots els avisos s'han enviat",
        "  3  no hi havia cap avis per enviar",
        "  4  alguns avisos han fallat",
        "  7  el servidor de correu no respon"
    })
@Component
public class OrdreAvisosEnviar implements Callable<Integer> {

    private final ServeiAvisos avisos;
    private final RepositoriPrestecs prestecs;
    private final Sortida sortida;
    private final GestorCancellacio cancellacio;
    private final Clock rellotge;

    @Option(names = "--dies-antelacio", defaultValue = "3",
            description = "Avisar dels venciments d'aqui a N dies. Per defecte: ${DEFAULT-VALUE}")
    private int diesAntelacio;

    @Option(names = "--des-de-stdin",
            description = "Llegeix identificadors d'empleat de l'entrada estandard, un per linia.")
    private boolean desDeStdin;

    @Option(names = "--simular", description = "Mostra a qui s'avisaria, sense enviar res.")
    private boolean simular;

    @Override
    public Integer call() throws IOException {
        List<Prestec> objectiu = seleccionarPrestecs();

        if (objectiu.isEmpty()) {
            sortida.info("No hi ha cap prestec que requereixi avis.");
            return CodiSortida.SENSE_RESULTATS;          // 3: NO es un error
        }

        sortida.info("Preparant %d avisos%s…".formatted(objectiu.size(), simular ? " (SIMULACIO)" : ""));

        var progres = new BarraProgres(objectiu.size(), sortida);     // s'autodesactiva sense terminal
        int enviats = 0;
        List<FalladaEnviament> fallades = new ArrayList<>();

        for (Prestec p : objectiu) {
            if (cancellacio.cancellat()) {
                progres.acabar();
                sortida.avis("Cancellat. Enviats %d de %d.".formatted(enviats, objectiu.size()));
                return CodiSortida.INTERROMPUT;
            }
            try {
                if (simular) {
                    // El resultat de la simulacio SI que es resultat: va a stdout
                    sortida.resultat("%s <%s> — \"%s\" venc el %s"
                            .formatted(p.nomDeLempleat(), p.correuDeLempleat(),
                                       p.titolDelMaterial(), p.getDataVenciment()));
                } else {
                    avisos.enviar(Avis.perVenciment(p));
                }
                enviats++;
            } catch (ServeiExternNoDisponibleException e) {
                // El servidor de correu caigut afecta TOTS: no te sentit continuar
                progres.acabar();
                throw e;                                  // el gestor el tradueix a 7
            } catch (BiblioTechException e) {
                fallades.add(new FalladaEnviament(p.getId(), p.correuDeLempleat(), e.getMessage()));
            } finally {
                progres.avancar();
            }
        }
        progres.acabar();

        if (!fallades.isEmpty()) {
            sortida.avis("%d avisos han fallat:".formatted(fallades.size()));
            fallades.forEach(f -> sortida.avis("  prestec #%d (%s): %s"
                    .formatted(f.idPrestec(), f.desti(), f.motiu())));
            sortida.info("Enviats %d de %d.".formatted(enviats, objectiu.size()));
            return CodiSortida.PARCIAL;                   // 4
        }

        sortida.correcte("Enviats %d avisos.".formatted(enviats));
        return CodiSortida.OK;
    }

    private List<Prestec> seleccionarPrestecs() throws IOException {
        LocalDate limit = LocalDate.now(rellotge).plusDays(diesAntelacio);

        if (!desDeStdin) {
            return prestecs.actiusQueVencenAbansDe(limit);
        }

        List<Long> ids = llegirIdsDeStdin();
        if (ids.isEmpty()) {
            sortida.avis("No s'ha llegit cap identificador de l'entrada estandard.");
            return List.of();
        }
        sortida.detall("Filtrant per %d empleats llegits de stdin".formatted(ids.size()));
        return prestecs.actiusQueVencenAbansDe(limit).stream()
                .filter(p -> ids.contains(p.getIdEmpleat()))
                .toList();
    }

    private List<Long> llegirIdsDeStdin() 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) {
                            sortida.avis("S'ignora la linia no numerica: '%s'".formatted(l));
                            return null;
                        }
                    })
                    .filter(Objects::nonNull)
                    .distinct()
                    .toList();
        }
    }
}

# Tots els venciments dels propers 3 dies
bibliotech avisos enviar

# Nomes als empleats del departament d'Arquitectura
bibliotech empleat llistar --departament=Arquitectura --format=csv \
  | cut -d';' -f1 | tail -n +2 \
  | bibliotech avisos enviar --des-de-stdin --dies-antelacio=7

# Veure a qui s'avisaria, sense enviar res
bibliotech avisos enviar --simular --format=json | jq -r '.[].correu'

#!/usr/bin/env bash
# /opt/bibliotech/scripts/avisos-diaris.sh
# Executar amb: 0 8 * * * /opt/bibliotech/scripts/avisos-diaris.sh
set -uo pipefail                    # sense -e: volem gestionar els codis nosaltres

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

for intent in $(seq 1 $MAX_INTENTS); do
  # El resultat al log; els diagnostics tambe, pero separables per si de cas
  bibliotech avisos enviar --dies-antelacio=3 --silencios >>"$LOG" 2>&1
  codi=$?

  case $codi in
    0) echo "$(date -Is) OK: avisos enviats" >>"$LOG"; exit 0 ;;
    3) echo "$(date -Is) Res per enviar avui"  >>"$LOG"; exit 0 ;;   # NO es una fallada
    4) echo "$(date -Is) AVIS: enviament parcial; revisa el log" >>"$LOG"
       mail -s "BiblioTech: avisos parcials" [email protected] <"$LOG"
       exit 0 ;;
    7) echo "$(date -Is) Correu no disponible; reintent $intent de $MAX_INTENTS" >>"$LOG"
       sleep $((intent * 120)) ;;                                    # 2, 4, 6 minuts
    *) echo "$(date -Is) ERROR irrecuperable (codi $codi)" >>"$LOG"
       mail -s "BiblioTech: fallada en els avisos" [email protected] <"$LOG"
       exit "$codi" ;;
  esac
done

echo "$(date -Is) ERROR: reintents esgotats" >>"$LOG"
mail -s "BiblioTech: correu caigut despres de 3 intents" [email protected] <"$LOG"
exit 7

/**
 * Formatador de taules per a consola, amb amplades automatiques.
 * Us:
 *   TaulaConsola.de(materials)
 *       .columna("ISBN", m -> m.getIsbn().valor())
 *       .columna("TITOL", Material::getTitol, 45)
 *       .columnaNumerica("LLIURES", Material::unitatsDisponibles)
 *       .ambTotals()
 *       .imprimir(sortida);
 */
public class TaulaConsola<T> {

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

    private final List<T> files;
    private final List<Columna<T>> columnes = new ArrayList<>();
    private boolean totals = false;

    private TaulaConsola(List<T> files) { this.files = files; }

    public static <T> TaulaConsola<T> de(List<T> files) { return new TaulaConsola<>(files); }

    // --- Definicio de columnes ---

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

    public TaulaConsola<T> columna(String titol, Function<T, String> extractor, int ampladaMaxima) {
        columnes.add(new Columna<>(titol, extractor, Alineacio.ESQUERRA, ampladaMaxima, null));
        return this;
    }

    public TaulaConsola<T> columnaNumerica(String titol, ToLongFunction<T> extractor) {
        columnes.add(new Columna<>(titol,
                t -> String.valueOf(extractor.applyAsLong(t)),
                Alineacio.DRETA, 15, extractor));
        return this;
    }

    public TaulaConsola<T> ambTotals() { this.totals = true; return this; }

    // --- Impressio ---

    public void imprimir(Sortida sortida) {
        if (columnes.isEmpty()) throw new IllegalStateException("Defineix almenys una columna");

        int[] amplades = calcularAmplades();
        ajustarAlTerminal(amplades);

        PrintStream out = sortida.out();

        if (sortida.mostrarDecoracio()) {
            out.println(fila(amplades, i -> columnes.get(i).titol()));
            out.println("-".repeat(ampladaTotal(amplades)));
        }

        for (T element : files) {
            out.println(fila(amplades, i -> valor(columnes.get(i), element, amplades[i])));
        }

        if (totals && sortida.mostrarDecoracio()) {
            out.println("-".repeat(ampladaTotal(amplades)));
            out.println(fila(amplades, this::totalDeColumna));
            out.printf("%d files%n", files.size());
        }
    }

    // --- Calcul d'amplades ---

    private int[] calcularAmplades() {
        int[] amplades = new int[columnes.size()];
        for (int i = 0; i < columnes.size(); i++) {
            Columna<T> c = columnes.get(i);
            int ampladaContingut = files.stream()
                    .map(c.extractor())
                    .mapToInt(String::length)
                    .max().orElse(0);
            // L'amplada es la major entre el titol i el contingut, limitada pel maxim
            amplades[i] = Math.min(c.ampladaMaxima(), Math.max(c.titol().length(), ampladaContingut));
        }
        return amplades;
    }

    /**
     * Si la taula no hi cap, retalla proporcionalment les columnes de text
     * mes amples, respectant un minim de 8 caracters.
     */
    private void ajustarAlTerminal(int[] amplades) {
        int disponible = ampladaTerminal();
        int total = ampladaTotal(amplades);
        if (total <= disponible) return;

        int exces = total - disponible;
        // Retallar de major a menor fins a absorbir l'exces
        List<Integer> candidates = IntStream.range(0, amplades.length)
                .boxed()
                .filter(i -> columnes.get(i).alineacio() == Alineacio.ESQUERRA)
                .sorted(Comparator.comparingInt((Integer i) -> amplades[i]).reversed())
                .toList();

        for (int i : candidates) {
            if (exces <= 0) break;
            int retallable = Math.max(0, amplades[i] - 8);
            int retall = Math.min(retallable, exces);
            amplades[i] -= retall;
            exces -= retall;
        }
    }

    private int ampladaTerminal() {
        // COLUMNS l'exporta el shell; si no hi es, fer servir el valor per defecte
        String columnes = System.getenv("COLUMNS");
        try {
            return columnes != null ? Integer.parseInt(columnes) : AMPLADA_TERMINAL_PER_DEFECTE;
        } catch (NumberFormatException e) {
            return AMPLADA_TERMINAL_PER_DEFECTE;
        }
    }

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

    // --- Format de celles ---

    private String fila(int[] amplades, IntFunction<String> cella) {
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < amplades.length; i++) {
            if (i > 0) sb.append(SEPARADOR);
            String text = retallar(cella.apply(i), amplades[i]);
            sb.append(columnes.get(i).alineacio() == Alineacio.DRETA
                    ? " ".repeat(amplades[i] - text.length()) + text
                    : text + " ".repeat(amplades[i] - text.length()));
        }
        return sb.toString().stripTrailing();     // sense espais al final: embruten en copiar
    }

    private String valor(Columna<T> c, T element, int amplada) {
        return retallar(c.extractor().apply(element), amplada);
    }

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

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

    // --- Tipus auxiliars ---

    private enum Alineacio { ESQUERRA, DRETA }

    private record Columna<T>(String titol,
                              Function<T, String> extractor,
                              Alineacio alineacio,
                              int ampladaMaxima,
                              ToLongFunction<T> sumador) { }
}

TaulaConsola.de(materials)
    .columna("ISBN", m -> m.getIsbn().valor())
    .columna("TITOL", Material::getTitol, 45)
    .columna("TIPUS", m -> m.tipus().name())
    .columnaNumerica("LLIURES", Material::unitatsDisponibles)
    .ambTotals()
    .imprimir(sortida);

ISBN            TITOL                             TIPUS   LLIURES
-----------------------------------------------------------------
978-0000000001  Java Eficac                       LLIBRE        2
978-0000000002  Patrons de Disseny                LLIBRE        0
978-0000000003  Refactoritzacio                   LLIBRE        1
-----------------------------------------------------------------
TOTAL                                                           3
3 files