pdf-tool-cli 1.1.0__py3-none-any.whl

pdf_tool_cli-1.1.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: pdf-tool-cli
+Version: 1.1.0
+Summary: Herramientas PDF (unir, dividir, comprimir, proteger…) como CLI para agentes y app de escritorio.
+License: MIT
+License-File: LICENSE
+Keywords: pdf,cli,agents,merge,split,compress
+Author: Juan Manuel Armero
+Author-email: juanmanuel.armero@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Provides-Extra: gui
+Requires-Dist: flet (==0.28.2) ; extra == "gui"
+Requires-Dist: platformdirs (>=4.2.0,<5.0.0)
+Requires-Dist: pydantic (>=2.6.0,<3.0.0)
+Requires-Dist: pymupdf (>=1.24.3,<2.0.0)
+Project-URL: Homepage, https://github.com/juanMaAV92/pdf-tool
+Project-URL: Repository, https://github.com/juanMaAV92/pdf-tool
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 📄 PDF Tool
+
+**Una app de escritorio sencilla para trabajar con tus PDFs — sin subir nada a internet.**
+
+<img width="980" height="680" alt="Screenshot 2026-06-15 at 6 54 49 PM" src="https://github.com/user-attachments/assets/adf416d8-bb05-478d-8a6d-31a35410af28" />
+
+Comprime, une, divide, protege y marca tus documentos —y conviértelos desde imágenes—
+desde tu propio ordenador. Gratis, de código abierto y sin anuncios.
+
+[![Descargar](https://img.shields.io/badge/⬇️_Descargar-última_versión-2ea44f?style=for-the-badge)](https://github.com/juanMaAV92/pdf-tool/releases/latest)
+
+[![CI](https://github.com/juanMaAV92/pdf-tool/actions/workflows/ci.yml/badge.svg)](https://github.com/juanMaAV92/pdf-tool/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/juanMaAV92/pdf-tool?label=versión)](https://github.com/juanMaAV92/pdf-tool/releases/latest)
+[![License: MIT](https://img.shields.io/badge/Licencia-MIT-blue.svg)](LICENSE)
+![Platform](https://img.shields.io/badge/macOS_·_Windows-lightgrey)
+
+</div>
+
+<!-- 📸 Añade aquí un screenshot o GIF de la app:
+     ![PDF Tool](docs/screenshot.png)
+     Es lo que más convence a quien entra al repo. -->
+
+---
+
+## ✨ Qué puedes hacer
+
+| | Herramienta | Para qué sirve |
+|---|---|---|
+| 🗜️ | **Comprimir PDF** | Reduce el peso de uno o varios PDFs hasta el tamaño en MB que elijas. |
+| 🔗 | **Unir PDFs** | Combina varios documentos en uno solo, en el orden que quieras y con el nombre que elijas. |
+| ✂️ | **Dividir PDF** | Separa un PDF en varios: por rangos de páginas, una página por archivo o cada N páginas. |
+| 🖼️ | **Imágenes a PDF** | Convierte cada imagen (JPG/PNG) en su propio PDF — y si quieres uno solo, únelos después. |
+| 🔒 | **Proteger PDF** | Añade o quita la contraseña de uno o varios PDFs a la vez. |
+| 💧 | **Marca de agua** | Repite un texto en diagonal sobre todas las páginas. |
+
+> 🔐 **Todo ocurre en tu equipo.** Tus archivos nunca salen de tu ordenador.
+
+En **Comprimir PDF**, el modo predeterminado busca la reducción máxima. También
+puedes elegir **Conservar texto y enlaces** desde el selector de modo; el icono
+de ayuda explica la diferencia.
+
+---
+
+## ⬇️ Descargar e instalar
+
+Ve a la **[página de descargas](https://github.com/juanMaAV92/pdf-tool/releases/latest)** y elige el archivo de tu sistema:
+
+### 🍎 macOS
+1. Descarga el archivo **`.dmg`** y ábrelo.
+2. Arrastra **PDF Tool** a la carpeta *Aplicaciones*.
+3. Ábrela desde *Aplicaciones*. macOS mostrará un aviso y **no** dejará abrirla aún
+   (es normal: la app no está firmada, pero es segura).
+4. Ve a  **Menú Apple () → Ajustes del Sistema → Privacidad y Seguridad**.
+5. Baja hasta la sección **Seguridad**: verás un mensaje que dice que se bloqueó *“PDF Tool”*.
+   Pulsa **Abrir de todas formas** y confirma con tu contraseña o Touch ID.
+   <br><sub>Solo hay que hacerlo la primera vez. A partir de ahí se abre con doble clic como cualquier app.</sub>
+
+### 🪟 Windows
+1. Descarga el **instalador** (`.exe`) y ejecútalo.
+2. Si aparece SmartScreen: **Más información** → **Ejecutar de todas formas**.
+   <br><sub>(El aviso sale porque el instalador no está firmado; es seguro.)</sub>
+
+> ✅ Tus ajustes se guardan fuera de la app, así que se conservan al actualizar. Cuando publique una nueva versión, la app te avisa con un banner.
+
+---
+
+## 🤖 Para agentes de IA y la línea de comandos
+
+Las mismas herramientas están disponibles como comando, pensado para agentes
+(Claude Code, Cursor, Copilot…) y scripts. Todo sigue ocurriendo en tu equipo.
+
+```bash
+pipx install pdf-tool-cli                    # solo la CLI (sin la app de escritorio)
+pdf-tool list --json                         # qué herramientas hay y qué aceptan
+pdf-tool compress informe.pdf --json         # comprimir y obtener el resultado en JSON
+pdf-tool merge a.pdf b.pdf --output-name todo
+echo "$CLAVE" | pdf-tool protect a.pdf --password-stdin
+```
+
+Cada herramienta tiene su ayuda (`pdf-tool compress --help`). Códigos de salida:
+`0` ok · `1` error al procesar · `2` uso inválido · `3` algún archivo del lote falló.
+`pipx install 'pdf-tool-cli[gui]'` instala además la app (comando `pdftool`).
+
+---
+
+## 🤝 Contribuir
+
+¡Las contribuciones son bienvenidas! Puedes abrir un *issue* con ideas o errores,
+o mandar un *pull request*. La arquitectura es modular: añadir una herramienta nueva
+es crear una carpeta y la app la descubre sola. En el [roadmap](docs/roadmap.md)
+está lo que viene: una CLI para agentes de IA, a la par con la app.
+
+<details>
+<summary><b>🛠️ Para desarrolladores (montar el proyecto en local)</b></summary>
+
+### Requisitos
+- Python 3.11+ y [Poetry](https://python-poetry.org/)
+
+### Arrancar
+```bash
+poetry install --all-extras   # incluye Flet (extra [gui]) para la app
+poetry run pdftool        # abre la app
+poetry run pytest         # corre los tests
+```
+
+### Añadir una herramienta nueva
+1. Crea `pdftool/tools/<id>/` con `params.py`, `logic.py` (función pura + tests),
+   `spec.py` (registra la herramienta, sin Flet), `panel.py` y un `__init__.py` vacío.
+2. La app la muestra en la barra lateral y la CLI la ofrece como `pdf-tool <id>`,
+   las dos automáticamente.
+
+La **lógica** (`logic.py`) no importa Flet y se prueba sin UI; la **UI** (`panel.py`)
+solo arma controles. Detalles en [AGENTS.md](AGENTS.md).
+
+### Publicar una versión (automatizado con GitHub Actions)
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```
+Eso dispara `release.yml`, que corre los tests, construye macOS (`.dmg`) y Windows
+(instalador Inno Setup) en paralelo, hornea la versión del tag en el build y crea
+un **GitHub Release en borrador** con ambos instaladores. Revísalo y pulsa
+**Publish release** para que las apps instaladas detecten la actualización.
+Si los instaladores se construyen bien, publica también el paquete en **PyPI**
+(Trusted Publishing, entorno `pypi` de GitHub; sin tokens).
+
+Los PRs que cambian la app, el empaquetado o sus dependencias ejecutan además
+**Package smoke**: construye e inspecciona el DMG de macOS y compila e instala de
+forma silenciosa el instalador de Windows. Antes de una release importante,
+seguir la [checklist manual](docs/release-smoke.md) para validar la ventana y los
+diálogos nativos.
+
+El número de versión es **el tag** — única fuente de verdad.
+
+### Build local (para depurar el empaquetado)
+```bash
+poetry run flet build macos      # -> build/macos/pdf-tool.app
+poetry run flet build windows    # -> build/windows/
+```
+
+</details>
+
+---
+
+<div align="center">
+<sub>Hecho con 🐍 Python + <a href="https://flet.dev">Flet</a> · Licencia <a href="LICENSE">MIT</a></sub>
+</div>
+

pdf_tool_cli-1.1.0.dist-info/RECORD

@@ -0,0 +1,66 @@
+pdftool/__init__.py,sha256=WBAFDUQGkc9SJZWu6dmQHTAxXUG5xf6imG6emenBA_o,170
+pdftool/cli/__init__.py,sha256=pQZ8WGZuslAR0-KXVyOO1vZe0pnWvhZ1mA9eH2STJEU,6289
+pdftool/cli/__main__.py,sha256=FwvSvCBK50eXZfN_hx8uQabEU5XS-BEBvm66BxTjsyI,59
+pdftool/cli/args.py,sha256=2_D1EB8N9u6kTtHb44NrDf9Kule3P4VbK-NaI4UeyNI,4662
+pdftool/cli/report.py,sha256=-zfi_lXlM1JC3-XanuecRzsh-xUY7aLpQIsfjK3REyI,2071
+pdftool/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdftool/core/atomic.py,sha256=KnMeGznQklI00gQgahcWTNHj4tPbPQahOuzHNdIi9h0,1511
+pdftool/core/batch.py,sha256=clt9F8kIL5FqjNOZaq9pYuLMxVS3q60-xQ0vx2vbdwE,3338
+pdftool/core/config.py,sha256=0QHkU0NlWzfAs6gFqWdU6atebageCdJJtKVt693tIxQ,2855
+pdftool/core/errors.py,sha256=OBcNR17H7THDaAjzDWG1ldsfVJ7xBoowJus_aSeI3nM,1284
+pdftool/core/jobs.py,sha256=OsHtjUQnXHRcNlGFZvZbCo4lCSu-eKcZWof0h-JmQqo,5672
+pdftool/core/logger.py,sha256=1A2kPvRdbo45o1Z5vP7NmLpR2CqHH7gSysRTOQVE_Z8,3234
+pdftool/core/naming.py,sha256=y9IBzlOOQUVZXTRV0fasDsExmJvyqyRBFxqtCG1KcTY,3193
+pdftool/core/plugin.py,sha256=zmSimrzoQ-5PeLjFhI-VpEwqwvlAdFGjPm-MXZklvv4,2780
+pdftool/core/registry.py,sha256=d-Y85c4vMT8Qr-Mz52MiaGF6Z4Ic84A2acWoRF54AR0,2055
+pdftool/core/thumbnails.py,sha256=7fKEoPbX1oA5cfY_kHivawgnfTGuR9jJtWQNA7J1nB8,1422
+pdftool/core/updater.py,sha256=idPQ2aczATwYLGQ6Cu5fXhlUhSsO5uKgUQv3stCxBDA,2407
+pdftool/main.py,sha256=e_sswy-GGcJqr64wUY7iHGs4vRMY5FFclXfwTC3bNeM,740
+pdftool/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdftool/tools/compress/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdftool/tools/compress/logic.py,sha256=ZImLu-LumdmSDFaBqc2UQyuyW9oC8HHuz7dEd7TmwWk,13563
+pdftool/tools/compress/panel.py,sha256=2loLSClDjLUj-k-dyOlmPCkAOsGcolD7AGEWdaSGnfQ,2705
+pdftool/tools/compress/params.py,sha256=iHDg_QdmH3xZQx-9VymTnfKPIgmaU_FmKOeamBn679c,642
+pdftool/tools/compress/spec.py,sha256=oFZKUN6DPhY8hSN1XnshxhVt6FPkIZj4Fwobg2_zuEo,532
+pdftool/tools/images2pdf/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdftool/tools/images2pdf/logic.py,sha256=fXyNNQVVQzDBcNUmcGYxSUyF7fWwZivHTEX7GvhiP-E,4216
+pdftool/tools/images2pdf/panel.py,sha256=nCABYZrsSUMyu45Xzl_nhvO8TGFHALRxq5AC6ojuccM,601
+pdftool/tools/images2pdf/params.py,sha256=OKhQNY5OpuaL6nVhFSRbOEAoLIUttbwqVS-soXNcqzA,213
+pdftool/tools/images2pdf/spec.py,sha256=Vw2xuwva62EbmKORlZZTM-nJZb6pO77gmKd9cZigjMI,580
+pdftool/tools/merge/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdftool/tools/merge/logic.py,sha256=KzTXkIG4GDIb3XNFMvLgaDSAP9f8CS7jGouoll3vOvc,1919
+pdftool/tools/merge/panel.py,sha256=piWOju5z6ud-L8L9ZVNkkmjq0jwm3dbp8G0Hal-ZDg4,1391
+pdftool/tools/merge/params.py,sha256=VTKRxa4ZNMwvIwhpnlC-aCRZcTMtdHz4GFqHaItmcUA,689
+pdftool/tools/merge/spec.py,sha256=c0awYK64h3GPYM1cygpesGTb2hjBXS9SA65lzyhpqzs,526
+pdftool/tools/protect/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdftool/tools/protect/logic.py,sha256=TWHyzWqOIQ9VU0TqBXHeaKNWGTcTDWhv5rdOY4vHEic,3171
+pdftool/tools/protect/panel.py,sha256=nYsYmZP3RgTeiB1hP2xcDcNDq5xM9QC6DIOwlJhSNqY,2738
+pdftool/tools/protect/params.py,sha256=qhQYvPuVzopzPg_2cWNlwq-F3qtbp0SYIkptidlRrzU,513
+pdftool/tools/protect/spec.py,sha256=-P3qvxS5x_VG5uNdM3J40qHSjJL1l-CtYhzkYm1beM0,516
+pdftool/tools/split/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdftool/tools/split/logic.py,sha256=vm-y3o0S9pPm3gd6jdOJBfJzQhaucDgkFzT3tyTzA78,4854
+pdftool/tools/split/panel.py,sha256=c8fICu12aGUs2G6f8Dekizi-CTEd0unlVnWElw46oeM,4670
+pdftool/tools/split/params.py,sha256=0fsqhFYcFlSiOLkg2K61qnSiGz_bewq0sBz5HrHVdDA,814
+pdftool/tools/split/spec.py,sha256=_6AKzirSVC3e8tWu2hs_S1kW2-D0hTo-9HlOrYtQOD0,523
+pdftool/tools/watermark/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdftool/tools/watermark/logic.py,sha256=ie39AelUiRJBEvX5wW1mXjwxtcxzIo-km6wNVvbWzAE,4244
+pdftool/tools/watermark/panel.py,sha256=3K3fiX0ap_3QyPsueiqx7t50GLiAnZKr0c9ZpOOrGpM,2120
+pdftool/tools/watermark/params.py,sha256=uutERPzkIOVtDzSA9OXsjYCF4dcc29hg-Vz4T2uL7-s,611
+pdftool/tools/watermark/spec.py,sha256=KQKQBag0Bsx8nq21IVsqSfoSYH4Wn3M31pWmNZuu5tQ,552
+pdftool/ui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdftool/ui/accessibility.py,sha256=b7bfTZf3SpIldMDKX8kcQtiMWiTwSun0PiSyHichmSc,1226
+pdftool/ui/app.py,sha256=dCZotEIqWadjuHnZQzrlnDJbmzpHlmjz7AcF_69OLMU,14418
+pdftool/ui/errors.py,sha256=QNOrgpqwLVjZpArAo123fr5RMuREC2YZO3eP-3AyheM,402
+pdftool/ui/file_list.py,sha256=fTJ7oafBQ0B6OVYvQJZs7mAxP00FHahlT75jKjeVcQ8,10541
+pdftool/ui/logs.py,sha256=WRZ8popiG6zgF-_b-DdzxyEnFwT0ELoLvZi18MHgB64,1703
+pdftool/ui/output_dir.py,sha256=2pxgM00kE7REhzcnyxk1BnMMMMd1Fc4pOWolIvHJUXA,4494
+pdftool/ui/panel_base.py,sha256=JkLp92muH3NB-hYd6qqvL4wr3kLCo3_oog9xgFuaxZw,24799
+pdftool/ui/platform.py,sha256=7N5R3DadObrqbZ2rfbFN9VxkfBH32CKywmflvxR5cA8,847
+pdftool/ui/registry.py,sha256=xW1afZYbmOppZTZVmFJ4QBgqN59ZwqhYT7tvV2Tc3Ho,2072
+pdftool/ui/theme.py,sha256=siyopw5U5HWsPLtl_1lFiSla_FRfQCLTHXezzhWOIdU,668
+pdftool/ui/thumbnails.py,sha256=IKeVPl2DqjXVM4aDklMjic6tTO8HBFmjMOG8wE60djE,5058
+pdf_tool_cli-1.1.0.dist-info/METADATA,sha256=6rp6SRMZoC-oh8Fi0IlKtgP6ZhPuMKKPHmSpwqX2PyM,7895
+pdf_tool_cli-1.1.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+pdf_tool_cli-1.1.0.dist-info/entry_points.txt,sha256=MkYurBGAWAzCn--whsJYB-RURm5V6n_q_lD930ftFAQ,71
+pdf_tool_cli-1.1.0.dist-info/licenses/LICENSE,sha256=vt-PHUat0X1Blgpf3iJ-zX8roxuSXMbSO4DZ4GVhUt0,1075
+pdf_tool_cli-1.1.0.dist-info/RECORD,,

pdf_tool_cli-1.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pdf_tool_cli-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+pdf-tool=pdftool.cli:main
+pdftool=pdftool.main:main
+

pdf_tool_cli-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Manuel Armero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdftool/__init__.py

@@ -0,0 +1,3 @@
+# La versión real la hornea CI desde el tag git al construir el release
+# (ver .github/workflows/release.yml). En desarrollo local queda como dev.
+__version__ = "1.1.0"

pdftool/cli/__init__.py

@@ -0,0 +1,179 @@
+"""`pdf-tool`: las herramientas de la app como línea de comandos (sin Flet).
+
+Los subcomandos salen del registro de specs y sus flags, de los params de cada
+herramienta: una herramienta nueva aparece aquí sin tocar este módulo.
+Códigos de salida: 0 ok · 1 error al procesar · 2 uso o params inválidos ·
+3 lote parcial (algún archivo falló).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any, TextIO
+
+from pdftool import __version__
+from pdftool.cli.args import add_params, build_params
+from pdftool.cli.report import error_to_dict, exit_code, render_text, result_to_dict
+from pdftool.core import registry
+from pdftool.core.errors import UserError, user_message
+from pdftool.core.plugin import ToolSpec
+
+EXIT_ERROR = 1
+EXIT_USAGE = 2
+
+
+class _UsageError(Exception):
+    def __init__(self, message: str, usage: str) -> None:
+        super().__init__(message)
+        self.usage = usage
+
+
+class _Parser(argparse.ArgumentParser):
+    """Un uso inválido lanza en vez de salir: así `--json` también lo reporta
+    en JSON. Los subcomandos heredan esta clase."""
+
+    def error(self, message: str):  # type: ignore[override]
+        raise _UsageError(f"{self.prog}: {message}", self.format_usage())
+
+
+def _build_parser(specs: Sequence[ToolSpec]) -> argparse.ArgumentParser:
+    parser = _Parser(
+        prog="pdf-tool",
+        description="Herramientas locales para PDFs: nada sale de tu equipo.",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True, metavar="COMANDO")
+    listing = sub.add_parser("list", help="Lista las herramientas disponibles.")
+    listing.add_argument("--json", action="store_true", help="Salida en JSON.")
+    for spec in specs:
+        tool = sub.add_parser(
+            spec.meta.id, help=spec.meta.name, description=spec.meta.description
+        )
+        tool.add_argument(
+            "inputs",
+            nargs="+",
+            type=Path,
+            metavar="ARCHIVO",
+            help="Archivos de entrada (" + ", ".join(spec.extensions) + ").",
+        )
+        add_params(tool, spec.params)
+        tool.add_argument("--json", action="store_true", help="Salida en JSON.")
+    return parser
+
+
+def _spec_to_dict(spec: ToolSpec) -> dict[str, Any]:
+    return {
+        "id": spec.meta.id,
+        "name": spec.meta.name,
+        "description": spec.meta.description,
+        "category": spec.meta.category,
+        "inputs": {
+            "min": spec.min_inputs,
+            "max": spec.max_inputs,
+            "extensions": list(spec.extensions),
+        },
+        "params": spec.params.model_json_schema(),
+    }
+
+
+def _print_json(data: Any) -> None:
+    print(json.dumps(data, ensure_ascii=False, indent=2))
+
+
+def _list(specs: Sequence[ToolSpec], as_json: bool) -> int:
+    if as_json:
+        _print_json([_spec_to_dict(s) for s in specs])
+    else:
+        for s in specs:
+            print(f"{s.meta.id:<11} {s.meta.name} — {s.meta.description}")
+    return 0
+
+
+def _check_inputs(spec: ToolSpec, inputs: list[Path]) -> list[Path]:
+    n = len(inputs)
+    if n < spec.min_inputs:
+        raise UserError(f"{spec.meta.id} necesita al menos {spec.min_inputs} archivos")
+    if spec.max_inputs is not None and n > spec.max_inputs:
+        raise UserError(
+            f"{spec.meta.id} acepta como máximo {spec.max_inputs} archivo(s)"
+        )
+    for path in inputs:
+        if not path.exists():
+            raise UserError(f"No existe: {path}")
+        if not path.is_file():
+            raise UserError(f"No es un archivo: {path}")
+        if path.suffix.lower().lstrip(".") not in spec.extensions:
+            expected = ", ".join(f".{e}" for e in spec.extensions)
+            raise UserError(f"{path.name}: se espera {expected}")
+    return [path.resolve() for path in inputs]
+
+
+def _fail(spec: ToolSpec, exc: BaseException, as_json: bool, code: int) -> int:
+    if as_json:
+        _print_json(error_to_dict(spec.meta.id, exc))
+    else:
+        message, detail = user_message(exc)
+        print(f"pdf-tool: {message}", file=sys.stderr)
+        if detail is not None:
+            print(f"detalle: {detail}", file=sys.stderr)
+    return code
+
+
+def _run(spec: ToolSpec, ns: argparse.Namespace, env, stdin) -> int:
+    try:
+        inputs = _check_inputs(spec, ns.inputs)
+        params = build_params(ns, spec.params, env=env, stdin=stdin)
+        if params.output_dir is not None and not params.output_dir.is_dir():
+            raise UserError(f"No existe la carpeta de salida: {params.output_dir}")
+    except UserError as exc:
+        return _fail(spec, exc, ns.json, EXIT_USAGE)
+    try:
+        result = spec.run(inputs, params)
+    except Exception as exc:
+        return _fail(spec, exc, ns.json, EXIT_ERROR)
+    if ns.json:
+        _print_json(result_to_dict(spec.meta.id, result))
+    else:
+        print(render_text(result))
+    return exit_code(result)
+
+
+def main(
+    argv: list[str] | None = None,
+    *,
+    stdin: TextIO | None = None,
+    env: Mapping[str, str] | None = None,
+) -> int:
+    # La lógica registra avisos por lote; sin handler, Python los escribiría
+    # en stderr y ensuciaría la salida. El resultado ya los reporta.
+    logging.getLogger("pdftool").addHandler(logging.NullHandler())
+    registry.discover()
+    specs = registry.get_specs()
+    parser = _build_parser(specs)
+    args = sys.argv[1:] if argv is None else argv
+    try:
+        ns = parser.parse_args(args)
+    except SystemExit as exc:  # --help/--version
+        return exc.code if isinstance(exc.code, int) else 0
+    except _UsageError as exc:
+        if "--json" in args:
+            tool_id = next((a for a in args if a in {s.meta.id for s in specs}), None)
+            _print_json(error_to_dict(tool_id, UserError(str(exc))))
+        else:
+            print(f"{exc.usage}{exc}", file=sys.stderr)
+        return EXIT_USAGE
+    if ns.command == "list":
+        return _list(specs, ns.json)
+    spec = next(s for s in specs if s.meta.id == ns.command)
+    return _run(
+        spec,
+        ns,
+        os.environ if env is None else env,
+        sys.stdin if stdin is None else stdin,
+    )

pdftool/cli/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from pdftool.cli import main
+
+sys.exit(main())

pdftool/cli/args.py

@@ -0,0 +1,138 @@
+"""Traduce los params Pydantic de una herramienta a flags de argparse (sin Flet).
+
+Cada campo `snake_case` se vuelve `--kebab-case`. Lo que no se pasa queda en
+None y no llega al modelo, así manda el default de Pydantic. Los campos
+secretos (`json_schema_extra={"secret": True}`) nunca son un flag: se leen de
+stdin con `--<campo>-stdin` o de la variable `PDFTOOL_<CAMPO>`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import types
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Annotated, Any, Literal, TextIO, Union, get_args, get_origin
+
+from pydantic import ValidationError
+from pydantic.fields import FieldInfo
+
+from pdftool.core.errors import UserError
+from pdftool.core.plugin import BaseParams
+
+_SCALARS = (int, float, str, Path)
+# Nombres que ya usa el comando (`pdf-tool <id> ARCHIVO... --json`) o argparse.
+RESERVED = frozenset({"json", "inputs", "command", "help", "version"})
+
+
+def _flag(name: str) -> str:
+    return "--" + name.replace("_", "-")
+
+
+def _env_var(name: str) -> str:
+    return f"PDFTOOL_{name.upper()}"
+
+
+def _is_secret(field: FieldInfo) -> bool:
+    extra = field.json_schema_extra
+    return isinstance(extra, dict) and extra.get("secret") is True
+
+
+def _strip_optional(annotation: Any) -> Any:
+    if get_origin(annotation) in (Union, types.UnionType):
+        args = [a for a in get_args(annotation) if a is not type(None)]
+        if len(args) == 1:
+            return args[0]
+    return annotation
+
+
+def _unannotated(annotation: Any) -> Any:
+    if get_origin(annotation) is Annotated:
+        return get_args(annotation)[0]
+    return annotation
+
+
+def _type_kwargs(name: str, annotation: Any) -> dict[str, Any]:
+    annotation = _strip_optional(annotation)
+    origin = get_origin(annotation)
+    if origin is Literal:
+        return {"choices": list(get_args(annotation))}
+    if origin is tuple:
+        items = tuple(_unannotated(i) for i in get_args(annotation))
+        if items and all(i in _SCALARS for i in items) and len(set(items)) == 1:
+            return {"type": items[0], "nargs": len(items)}
+    if annotation in _SCALARS:
+        return {"type": annotation}
+    raise TypeError(f"Campo {name!r}: tipo {annotation!r} no soportado por la CLI")
+
+
+def _help(field: FieldInfo) -> str:
+    text = field.description or ""
+    if not field.is_required() and field.default not in (None, ""):
+        default = field.default
+        if isinstance(default, tuple):
+            default = " ".join(str(v) for v in default)
+        text += f" (por defecto: {default})"
+    return text
+
+
+def add_params(parser: argparse.ArgumentParser, params: type[BaseParams]) -> None:
+    for name, field in params.model_fields.items():
+        if name in RESERVED:
+            raise TypeError(f"Campo {name!r}: nombre reservado por la CLI")
+        if _is_secret(field):
+            parser.add_argument(
+                f"{_flag(name)}-stdin",
+                dest=f"{name}_stdin",
+                action="store_true",
+                help=f"{field.description or name} Se lee de la primera línea de "
+                f"stdin (o de la variable {_env_var(name)}).",
+            )
+            continue
+        parser.add_argument(
+            _flag(name),
+            dest=name,
+            default=None,
+            required=field.is_required(),
+            help=_help(field),
+            **_type_kwargs(name, field.annotation),
+        )
+
+
+def _secret_value(
+    name: str, ns: argparse.Namespace, env: Mapping[str, str], stdin: TextIO
+) -> str | None:
+    if getattr(ns, f"{name}_stdin", False):
+        return stdin.readline().rstrip("\r\n")
+    return env.get(_env_var(name))
+
+
+def build_params(
+    ns: argparse.Namespace,
+    params: type[BaseParams],
+    *,
+    env: Mapping[str, str],
+    stdin: TextIO,
+) -> BaseParams:
+    values: dict[str, Any] = {}
+    for name, field in params.model_fields.items():
+        value: Any
+        if _is_secret(field):
+            value = _secret_value(name, ns, env, stdin)
+            if value is None and field.is_required():
+                raise UserError(
+                    f"Falta {name}: pásalo con {_flag(name)}-stdin "
+                    f"o la variable {_env_var(name)}"
+                )
+        else:
+            value = getattr(ns, name, None)
+            if isinstance(value, list):
+                value = tuple(value)
+        if value is not None:
+            values[name] = value
+    try:
+        return params(**values)
+    except ValidationError as exc:
+        error = exc.errors()[0]
+        field_name = str(error["loc"][0]) if error["loc"] else ""
+        raise UserError(f"{_flag(field_name)}: {error['msg']}") from exc

pdftool/cli/report.py

@@ -0,0 +1,71 @@
+"""Presenta un `ToolResult` como texto para personas o JSON para agentes."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pdftool.core.errors import user_message
+from pdftool.core.plugin import FileResult, ToolResult
+
+# Algún archivo del lote falló, pero otros salieron (ver `exit_code`).
+EXIT_PARTIAL = 3
+
+
+def _path(path: Path | None) -> str | None:
+    return None if path is None else str(path)
+
+
+def _item_to_dict(item: FileResult) -> dict[str, Any]:
+    return {
+        "input": _path(item.input_path),
+        "output": _path(item.output_path),
+        "ok": item.ok,
+        "message": item.message,
+        "warnings": list(item.warnings),
+        "metrics": dict(item.metrics),
+    }
+
+
+def _all_ok(result: ToolResult) -> bool:
+    return all(item.ok for item in result.items or [])
+
+
+def result_to_dict(tool_id: str, result: ToolResult) -> dict[str, Any]:
+    return {
+        "ok": _all_ok(result),
+        "tool": tool_id,
+        "summary": result.summary,
+        "outputs": [str(p) for p in result.outputs],
+        "items": None
+        if result.items is None
+        else [_item_to_dict(i) for i in result.items],
+        "warnings": list(result.warnings),
+        "metrics": dict(result.metrics),
+    }
+
+
+def error_to_dict(tool_id: str | None, exc: BaseException) -> dict[str, Any]:
+    message, detail = user_message(exc)
+    return {
+        "ok": False,
+        "tool": tool_id,
+        "error": {"message": message, "detail": detail},
+    }
+
+
+def render_text(result: ToolResult) -> str:
+    lines = [result.summary]
+    if result.items is None:
+        lines += [str(p) for p in result.outputs]
+    else:
+        for item in result.items:
+            mark = "✓" if item.ok else "✗"
+            lines.append(f"{mark} {item.input_path.name}: {item.message}")
+            lines += [f"  aviso: {w}" for w in item.warnings]
+    lines += [f"aviso: {w}" for w in result.warnings]
+    return "\n".join(lines)
+
+
+def exit_code(result: ToolResult) -> int:
+    return 0 if _all_ok(result) else EXIT_PARTIAL