tabella-docs 2.0.1__tar.gz → 2.0.3__tar.gz

{tabella_docs-2.0.1/tabella_docs.egg-info → tabella_docs-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tabella-docs
-Version: 2.0.1
+Version: 2.0.3
 Summary: Portable document lifecycle suite — create (.docx/.xlsx/.pptx/.pdf/.odt/.ods/.odp), convert (pandoc), and read (anydoc + LiteParse OCR) documents. Agent Plugins v1 compatible.
 Author-email: D Yiapanis <d@yiapanis.co>
 License-Expression: MIT
@@ -23,9 +23,9 @@ Provides-Extra: create
 Requires-Dist: python-docx<2.0,>=1.0; extra == "create"
 Requires-Dist: openpyxl<4.0,>=3.1; extra == "create"
 Requires-Dist: python-pptx<2.0,>=0.6; extra == "create"
-Requires-Dist: weasyprint<70.0,>=60.0; extra == "create"
+Requires-Dist: weasyprint<71.0,>=70.0; extra == "create"
 Requires-Dist: odfpy<2.0,>=1.4; extra == "create"
-Requires-Dist: Pillow<13.0,>=10.0; extra == "create"
+Requires-Dist: Pillow<14.0,>=10.0; extra == "create"
 Requires-Dist: lxml<7.0,>=5.0; extra == "create"
 Provides-Extra: read
 Requires-Dist: firecrawl-anydoc<0.3.0,>=0.1.1; extra == "read"
@@ -36,9 +36,9 @@ Provides-Extra: all
 Requires-Dist: python-docx<2.0,>=1.0; extra == "all"
 Requires-Dist: openpyxl<4.0,>=3.1; extra == "all"
 Requires-Dist: python-pptx<2.0,>=0.6; extra == "all"
-Requires-Dist: weasyprint<70.0,>=60.0; extra == "all"
+Requires-Dist: weasyprint<71.0,>=70.0; extra == "all"
 Requires-Dist: odfpy<2.0,>=1.4; extra == "all"
-Requires-Dist: Pillow<13.0,>=10.0; extra == "all"
+Requires-Dist: Pillow<14.0,>=10.0; extra == "all"
 Requires-Dist: lxml<7.0,>=5.0; extra == "all"
 Requires-Dist: firecrawl-anydoc<0.3.0,>=0.1.1; extra == "all"
 Requires-Dist: liteparse<3.0.0,>=2.0.0; extra == "all"
@@ -119,7 +119,7 @@ Or install only the modules you need:
 ```bash
 pip install tabella-docs[create]    # python-docx, openpyxl, python-pptx, weasyprint, odfpy
 pip install tabella-docs[read]      # firecrawl-anydoc, liteparse, PyMuPDF
-pip install tabella-docs[convert]   # no python deps (needs system pandoc + texlive-xetex)
+pip install tabella-docs[convert]   # no python deps (needs system pandoc; a TeX engine only for pdf output)
 ```
 
 ## Modules
@@ -189,8 +189,8 @@ Set `DOCS_VENV_PYTHON` to point to it:
 
 ```bash
 # Create a dedicated venv
-python -m venv ~/.venvs/docs
-~/.venvs/docs/bin/pip install python-docx openpyxl python-pptx weasyprint odfpy Pillow lxml PyMuPDF firecrawl-anydoc liteparse
+python -m venv ~/.venvs/docs/venv
+~/.venvs/docs/venv/bin/pip install python-docx openpyxl python-pptx weasyprint odfpy Pillow lxml PyMuPDF firecrawl-anydoc liteparse
 ```
 
 Or install the libraries into your main Python environment:
@@ -202,7 +202,7 @@ pip install tabella-docs[create]
 ### Read module
 
 ```bash
-~/.venvs/docs/bin/pip install firecrawl-anydoc liteparse PyMuPDF
+~/.venvs/docs/venv/bin/pip install firecrawl-anydoc liteparse PyMuPDF
 ```
 
 Or:
@@ -240,6 +240,23 @@ sudo apt install libcairo2 libpango-1.0-0 libgdk-pixbuf-2.0-0
 brew install cairo pango gdk-pixbuf
 ```
 
+### Windows
+
+tabella runs natively on Windows 10/11 (64-bit, Python 3.10+); all five MCP
+tools are exercised on `windows-latest` in CI. Native dependencies, installed
+per feature:
+
+- **PDF creation (WeasyPrint)** — the
+  [GTK3 runtime installer](https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer)
+  (its default install location is on WeasyPrint's search path)
+- **Convert** — [pandoc](https://pandoc.org/installing.html); a TeX engine
+  (e.g. MiKTeX) only when the *output* format is PDF
+- **OCR fallback** — [Tesseract for Windows](https://github.com/UB-Mannheim/tesseract/wiki),
+  only for scanned PDFs and images
+
+The first-run dependency venv bootstraps natively on Windows (stdlib venv
+module — no bash, MSYS2, or WSL required).
+
 ## Installation from source
 
 ```bash
@@ -252,7 +269,7 @@ pip install -e ".[all]"
 
 | Variable | Purpose | Default |
 |----------|---------|---------|
-| `DOCS_VENV_PYTHON` | Python binary for document libraries | `PLUGIN_DATA/venv/bin/python` or `~/.venvs/docs/bin/python` |
+| `DOCS_VENV_PYTHON` | Python binary for document libraries | `PLUGIN_DATA/venv/bin/python` or `~/.venvs/docs/venv/bin/python` |
 | `DOCS_OUTPUT_DIR` | Default output directory for generated documents | `~/Documents` |
 | `PLUGIN_DATA` | Client-managed data directory (set by v1 client) | — |
 | `PLUGIN_ROOT` | Plugin root directory (set by v1 client) | — |
@@ -260,10 +277,11 @@ pip install -e ".[all]"
 ### Automatic bootstrap
 
 On first startup, the MCP server checks if the docs venv exists. If not,
-it runs `scripts/setup.sh` to create a venv in `PLUGIN_DATA` (provided by
-the v1 client) or `~/.venvs/docs` as fallback, and installs all dependencies:
+it creates one in `PLUGIN_DATA` (provided by the v1 client) or
+`~/.venvs/docs` as fallback, and installs all dependencies:
 python-docx, openpyxl, python-pptx, weasyprint, odfpy, PyMuPDF,
-firecrawl-anydoc, liteparse.
+firecrawl-anydoc, liteparse. On POSIX this runs `scripts/setup.sh`; on
+Windows the venv is built with the standard library's `venv` module.
 
 This means the v1 package is fully self-contained — no manual pip install
 required. The bootstrap runs once; subsequent startups use the existing venv.

{tabella_docs-2.0.1 → tabella_docs-2.0.3}/README.md

@@ -70,7 +70,7 @@ Or install only the modules you need:
 ```bash
 pip install tabella-docs[create]    # python-docx, openpyxl, python-pptx, weasyprint, odfpy
 pip install tabella-docs[read]      # firecrawl-anydoc, liteparse, PyMuPDF
-pip install tabella-docs[convert]   # no python deps (needs system pandoc + texlive-xetex)
+pip install tabella-docs[convert]   # no python deps (needs system pandoc; a TeX engine only for pdf output)
 ```
 
 ## Modules
@@ -140,8 +140,8 @@ Set `DOCS_VENV_PYTHON` to point to it:
 
 ```bash
 # Create a dedicated venv
-python -m venv ~/.venvs/docs
-~/.venvs/docs/bin/pip install python-docx openpyxl python-pptx weasyprint odfpy Pillow lxml PyMuPDF firecrawl-anydoc liteparse
+python -m venv ~/.venvs/docs/venv
+~/.venvs/docs/venv/bin/pip install python-docx openpyxl python-pptx weasyprint odfpy Pillow lxml PyMuPDF firecrawl-anydoc liteparse
 ```
 
 Or install the libraries into your main Python environment:
@@ -153,7 +153,7 @@ pip install tabella-docs[create]
 ### Read module
 
 ```bash
-~/.venvs/docs/bin/pip install firecrawl-anydoc liteparse PyMuPDF
+~/.venvs/docs/venv/bin/pip install firecrawl-anydoc liteparse PyMuPDF
 ```
 
 Or:
@@ -191,6 +191,23 @@ sudo apt install libcairo2 libpango-1.0-0 libgdk-pixbuf-2.0-0
 brew install cairo pango gdk-pixbuf
 ```
 
+### Windows
+
+tabella runs natively on Windows 10/11 (64-bit, Python 3.10+); all five MCP
+tools are exercised on `windows-latest` in CI. Native dependencies, installed
+per feature:
+
+- **PDF creation (WeasyPrint)** — the
+  [GTK3 runtime installer](https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer)
+  (its default install location is on WeasyPrint's search path)
+- **Convert** — [pandoc](https://pandoc.org/installing.html); a TeX engine
+  (e.g. MiKTeX) only when the *output* format is PDF
+- **OCR fallback** — [Tesseract for Windows](https://github.com/UB-Mannheim/tesseract/wiki),
+  only for scanned PDFs and images
+
+The first-run dependency venv bootstraps natively on Windows (stdlib venv
+module — no bash, MSYS2, or WSL required).
+
 ## Installation from source
 
 ```bash
@@ -203,7 +220,7 @@ pip install -e ".[all]"
 
 | Variable | Purpose | Default |
 |----------|---------|---------|
-| `DOCS_VENV_PYTHON` | Python binary for document libraries | `PLUGIN_DATA/venv/bin/python` or `~/.venvs/docs/bin/python` |
+| `DOCS_VENV_PYTHON` | Python binary for document libraries | `PLUGIN_DATA/venv/bin/python` or `~/.venvs/docs/venv/bin/python` |
 | `DOCS_OUTPUT_DIR` | Default output directory for generated documents | `~/Documents` |
 | `PLUGIN_DATA` | Client-managed data directory (set by v1 client) | — |
 | `PLUGIN_ROOT` | Plugin root directory (set by v1 client) | — |
@@ -211,10 +228,11 @@ pip install -e ".[all]"
 ### Automatic bootstrap
 
 On first startup, the MCP server checks if the docs venv exists. If not,
-it runs `scripts/setup.sh` to create a venv in `PLUGIN_DATA` (provided by
-the v1 client) or `~/.venvs/docs` as fallback, and installs all dependencies:
+it creates one in `PLUGIN_DATA` (provided by the v1 client) or
+`~/.venvs/docs` as fallback, and installs all dependencies:
 python-docx, openpyxl, python-pptx, weasyprint, odfpy, PyMuPDF,
-firecrawl-anydoc, liteparse.
+firecrawl-anydoc, liteparse. On POSIX this runs `scripts/setup.sh`; on
+Windows the venv is built with the standard library's `venv` module.
 
 This means the v1 package is fully self-contained — no manual pip install
 required. The bootstrap runs once; subsequent startups use the existing venv.

{tabella_docs-2.0.1 → tabella_docs-2.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tabella-docs"
-version = "2.0.1"
+version = "2.0.3"
 description = "Portable document lifecycle suite — create (.docx/.xlsx/.pptx/.pdf/.odt/.ods/.odp), convert (pandoc), and read (anydoc + LiteParse OCR) documents. Agent Plugins v1 compatible."
 readme = "README.md"
 license = "MIT"
@@ -31,9 +31,9 @@ create = [
     "python-docx>=1.0,<2.0",
     "openpyxl>=3.1,<4.0",
     "python-pptx>=0.6,<2.0",
-    "weasyprint>=60.0,<70.0",
+    "weasyprint>=70.0,<71.0",
     "odfpy>=1.4,<2.0",
-    "Pillow>=10.0,<13.0",
+    "Pillow>=10.0,<14.0",
     "lxml>=5.0,<7.0",
 ]
 read = [
@@ -46,9 +46,9 @@ all = [
     "python-docx>=1.0,<2.0",
     "openpyxl>=3.1,<4.0",
     "python-pptx>=0.6,<2.0",
-    "weasyprint>=60.0,<70.0",
+    "weasyprint>=70.0,<71.0",
     "odfpy>=1.4,<2.0",
-    "Pillow>=10.0,<13.0",
+    "Pillow>=10.0,<14.0",
     "lxml>=5.0,<7.0",
     "firecrawl-anydoc>=0.1.1,<0.3.0",
     "liteparse>=2.0.0,<3.0.0",

{tabella_docs-2.0.1 → tabella_docs-2.0.3}/tabella/__init__.py

@@ -11,7 +11,9 @@ from __future__ import annotations
 import os
 from pathlib import Path
 
-__version__ = "1.0.0"
+from .bootstrap import resolve_venv_python
+
+__version__ = "2.0.3"
 
 # ── Configuration ─────────────────────────────────────────────
 
@@ -21,19 +23,11 @@ def get_docs_venv_python() -> str:
     Resolution order:
     1. DOCS_VENV_PYTHON env var (explicit override)
     2. PLUGIN_DATA/venv/bin/python (v1 client-managed data directory)
-    3. ~/.venvs/docs/bin/python (fallback)
-    """
-    explicit = os.environ.get("DOCS_VENV_PYTHON")
-    if explicit and Path(explicit).exists():
-        return explicit
+    3. ~/.venvs/docs/venv/bin/python (fallback)
 
-    plugin_data = os.environ.get("PLUGIN_DATA")
-    if plugin_data:
-        p = Path(plugin_data) / "venv" / "bin" / "python"
-        if p.exists():
-            return str(p)
-
-    return str(Path.home() / ".venvs" / "docs" / "bin" / "python")
+    Delegates to tabella.bootstrap so the path can only be wrong in one place.
+    """
+    return resolve_venv_python()
 
 
 def get_output_dir() -> Path:

tabella_docs-2.0.3/tabella/bootstrap.py

@@ -0,0 +1,144 @@
+"""Shared docs-venv bootstrap for the stdio and HTTP servers.
+
+`docs_root` is the directory that owns the venv; the venv itself always lives
+at `<docs_root>/venv`, which is exactly what scripts/setup.sh builds. Keep
+those two in step: the interpreter returned here is the one setup.sh created,
+and `tests/test_bootstrap_paths.py` asserts that instead of hard-coding a path
+that can drift again.
+
+Checks DOCS_VENV_PYTHON first. Otherwise the root is PLUGIN_DATA (provided by
+the v1 client) or ~/.venvs/docs.
+
+Platform notes:
+- POSIX runs scripts/setup.sh via bash.
+- Windows has no bash on a stock box — the venv is built with the stdlib
+  venv module + the venv's own pip, mirroring setup.sh
+  (--require-hashes -r requirements-pinned.txt).
+- The venv layout differs: bin/python vs Scripts/python.exe.
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def docs_root() -> Path:
+    """Directory that owns the docs venv (the argument setup.sh takes)."""
+    plugin_data = os.environ.get("PLUGIN_DATA")
+    if plugin_data:
+        return Path(plugin_data)
+    return Path.home() / ".venvs" / "docs"
+
+
+def venv_python_path() -> str:
+    """Interpreter inside the docs venv — `<docs_root>/venv`, as setup.sh builds it."""
+    venv_dir = docs_root() / "venv"
+    if os.name == "nt":
+        return str(venv_dir / "Scripts" / "python.exe")
+    return str(venv_dir / "bin" / "python")
+
+
+def resolve_venv_python() -> str:
+    """Interpreter to use, honouring an explicit DOCS_VENV_PYTHON override."""
+    explicit = os.environ.get("DOCS_VENV_PYTHON")
+    if explicit and Path(explicit).exists():
+        return explicit
+    return venv_python_path()
+
+
+def _venv_ready(venv_python: str) -> bool:
+    """Is this a *usable* docs venv, not just a leftover interpreter?
+
+    Existence alone is not enough: an interrupted first-run install leaves
+    bin/python behind with none of the packages, and every later start then
+    accepts it and fails at import time. A sentinel marks a completed install;
+    a venv without one is probed once (cheap) and adopted only if the imports
+    work — existing venvs created before the sentinel existed are not
+    re-bootstrapped for nothing.
+    """
+    if not Path(venv_python).exists():
+        return False
+    marker = Path(venv_python).parent.parent / ".tabella-deps-ok"
+    if marker.exists():
+        return True
+    # weasyprint is deliberately absent from this probe: importing it needs
+    # pango/GTK, which a host may legitimately lack (PDF then fails at call
+    # time with a clear error). Everything else is pure Python or bundled.
+    try:
+        probe = subprocess.run(
+            [venv_python, "-c", "import docx, openpyxl, pptx, odf, anydoc, liteparse, pymupdf"],
+            capture_output=True, text=True, timeout=120,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False  # hung or unexecutable: treat as not ready, rebuild
+    if probe.returncode == 0:
+        try:
+            marker.write_text("")
+        except OSError:
+            pass  # a read-only venv is still usable; the probe will run again
+        return True
+    return False
+
+
+def ensure_venv() -> str:
+    """Return the docs-venv interpreter, bootstrapping it on first use."""
+    explicit = os.environ.get("DOCS_VENV_PYTHON")
+    if explicit and Path(explicit).exists():
+        return explicit  # the operator named an interpreter: use it as-is
+
+    venv_python = venv_python_path()
+    if _venv_ready(venv_python):
+        return venv_python
+
+    root = docs_root()
+    root.mkdir(parents=True, exist_ok=True)  # ~/.venvs may not exist on a cold host
+    venv_dir = root / "venv"
+    marker = venv_dir / ".tabella-deps-ok"
+    plugin_root = Path(__file__).parent.parent.resolve()
+
+    if os.name == "nt":
+        # No bash on a stock Windows box — build the venv with the stdlib
+        # venv module + the venv's own pip, mirroring scripts/setup.sh.
+        pinned = plugin_root / "requirements-pinned.txt"
+        sys.stderr.write("tabella: bootstrapping docs venv (first run)...\n")
+        result = subprocess.run(
+            [sys.executable, "-m", "venv", str(venv_dir)],
+            capture_output=True, text=True, timeout=600,
+        )
+        if result.returncode == 0:
+            subprocess.run(
+                [venv_python, "-m", "pip", "install", "--quiet", "--upgrade", "pip"],
+                capture_output=True, text=True, timeout=600,
+            )
+            result = subprocess.run(
+                [venv_python, "-m", "pip", "install", "--quiet", "--require-hashes",
+                 "-r", str(pinned)],
+                capture_output=True, text=True, timeout=600,
+            )
+        if result.returncode != 0:
+            sys.stderr.write(f"tabella: bootstrap failed: {result.stderr[:500]}\n")
+        elif Path(venv_python).exists():
+            marker.write_text("")
+            sys.stderr.write("tabella: venv ready\n")
+        return venv_python
+
+    # POSIX bootstrap: run the setup script on the docs root — it creates
+    # <docs_root>/venv, which is what venv_python points at.
+    setup_script = plugin_root / "scripts" / "setup.sh"
+    if not setup_script.exists():
+        sys.stderr.write(f"tabella: setup script not found at {setup_script}\n")
+        return venv_python  # let tool calls fail with a helpful error
+
+    sys.stderr.write("tabella: bootstrapping docs venv (first run)...\n")
+    result = subprocess.run(
+        ["bash", str(setup_script), str(root)],
+        capture_output=True, text=True, timeout=300,
+    )
+    if result.returncode != 0:
+        sys.stderr.write(f"tabella: bootstrap failed: {result.stderr[:500]}\n")
+    elif Path(venv_python).exists():
+        marker.write_text("")
+        sys.stderr.write("tabella: venv ready\n")
+
+    return venv_python

{tabella_docs-2.0.1 → tabella_docs-2.0.3}/tabella/convert.py

@@ -5,6 +5,7 @@ Output directory is configurable via DOCS_OUTPUT_DIR (defaults to ~/Documents).
 Merged from the doc_convert plugin.
 """
 
+import re
 import json
 import logging
 import shutil
@@ -17,11 +18,11 @@ from .utils import _get_output_dir, _is_in_output_dir, _resolve_output_dir
 logger = logging.getLogger(__name__)
 
 
-def _check_deps() -> Optional[str]:
-    """Return error string if pandoc or LaTeX is missing, else None."""
+def _check_deps(needs_tex: bool = False) -> Optional[str]:
+    """Return error string if pandoc — or, for pdf targets, LaTeX — is missing."""
     if not shutil.which("pandoc"):
         return "pandoc is not installed. Install it (e.g. `sudo apt install pandoc`)."
-    if not shutil.which("pdflatex") and not shutil.which("xelatex"):
+    if needs_tex and not shutil.which("pdflatex") and not shutil.which("xelatex"):
         return "No LaTeX engine found. Install texlive (e.g. `sudo apt install texlive-xetex`)."
     return None
 
@@ -51,17 +52,15 @@ def doc_convert(
                      When omitted, pandoc infers from file extension.
         output_path: Optional absolute path for the output file.
                      When omitted, writes to the user's documents directory.
-        extra_args:  Optional extra pandoc CLI flags (e.g. ["--toc", "-V", "geometry:margin=1in"]).
+        extra_args:  Optional extra pandoc CLI flags (e.g. ["--toc", "-Vmargin=1in"]).
+                     NOTE: -V must be a single token ("-Vkey=value") — the
+                     two-token "-V key=value" form is rejected by the allowlist.
         category:    Optional subfolder under ~/documents/ (e.g. "reports", "invoices").
 
     Returns:
         {"success": bool, "output_path": str, "from_format": str, "to_format": str,
          "pdf_engine": str | None, "message": str}
     """
-    dep_err = _check_deps()
-    if dep_err:
-        return {"success": False, "error": dep_err}
-
     src = Path(input_path).expanduser().resolve()
     if not src.exists():
         return {"success": False, "error": f"Source file not found: {src}"}
@@ -69,6 +68,13 @@ def doc_convert(
     # Determine formats
     src_fmt = from_format or _infer_format(src.suffix.lstrip(".").lower())
     tgt_fmt = to_format.lower()
+    _check_format(src_fmt, "from_format")
+    _check_format(tgt_fmt, "to_format")
+
+    # pandoc is always required; a TeX engine only for pdf output
+    dep_err = _check_deps(tgt_fmt == "pdf")
+    if dep_err:
+        return {"success": False, "error": dep_err}
 
     # Determine output path
     if output_path:
@@ -93,7 +99,20 @@ def doc_convert(
         engine = _pdf_engine()
         cmd.extend(["--pdf-engine", engine])
     if extra_args:
-        cmd.extend(extra_args)
+        # strict allowlist — pandoc can execute arbitrary code via --filter/
+        # --lua-filter/--pdf-engine, so only formatting flags are honored
+        # (catalog review #2026-10-16, finding 1).
+        allowed = {"--toc", "--number-sections"}
+        for a in extra_args:
+            if a in allowed:
+                cmd.append(a)
+            elif re.match(r"^-V\S*=", a):
+                cmd.append(a)
+            else:
+                raise ValueError(
+                    f"unsupported pandoc argument {a!r}: extra_args allows only "
+                    "--toc, --number-sections and -V <key>=<value>"
+                )
 
     try:
         result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
@@ -138,6 +157,22 @@ def _infer_format(ext: str) -> str:
     return mapping.get(ext, ext)
 
 
+# Pandoc treats a format name ending in ".lua" as a path to a custom Lua
+# reader/writer and executes it with the full Lua stdlib (os.execute) —
+# same code-exec class as --lua-filter via a different argument. Restrict
+# format names to pandoc's built-in name grammar (catalog finding 2026-10-17).
+_FORMAT_RE = re.compile(r"^[a-z0-9_]+([+-][a-z0-9_]+)*$")
+
+
+def _check_format(name: str, which: str) -> None:
+    """Reject anything that isn't a built-in pandoc format name."""
+    if not _FORMAT_RE.match(name):
+        raise ValueError(
+            f"unsupported {which} {name!r}: must be a built-in pandoc format "
+            "(alphanumeric/underscore, optional +ext/-ext modifiers)"
+        )
+
+
 def _handle_doc_convert(args: dict, **kwargs) -> str:
     """Handler wrapper for doc_convert tool."""
     result = doc_convert(**args)