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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tabella-docs
-Version: 2.0.1
+Version: 2.0.2
 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
@@ -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
@@ -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
@@ -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.2}/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
@@ -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
@@ -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.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tabella-docs"
-version = "2.0.1"
+version = "2.0.2"
 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"

tabella_docs-2.0.2/tabella/bootstrap.py

@@ -0,0 +1,83 @@
+"""Shared docs-venv bootstrap for the stdio and HTTP servers.
+
+Returns the path to the docs venv Python, bootstrapping if needed.
+
+Checks DOCS_VENV_PYTHON first. If unset or the venv doesn't exist, one is
+created in 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 ensure_venv() -> str:
+    # If DOCS_VENV_PYTHON is set and exists, use it
+    venv_python = os.environ.get("DOCS_VENV_PYTHON")
+    if venv_python and Path(venv_python).exists():
+        return venv_python
+
+    # Determine where to create the venv
+    plugin_data = os.environ.get("PLUGIN_DATA")
+    if plugin_data:
+        venv_dir = Path(plugin_data) / "venv"
+    else:
+        venv_dir = Path.home() / ".venvs" / "docs"
+
+    if os.name == "nt":
+        venv_python = str(venv_dir / "Scripts" / "python.exe")
+    else:
+        venv_python = str(venv_dir / "bin" / "python")
+
+    if venv_dir.exists() and Path(venv_python).exists():
+        return venv_python
+
+    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:
+            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")
+        else:
+            sys.stderr.write("tabella: venv ready\n")
+        return venv_python
+
+    # POSIX bootstrap: run the setup script
+    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")
+    data_dir = str(venv_dir.parent) if plugin_data else str(venv_dir)
+    result = subprocess.run(
+        ["bash", str(setup_script), data_dir],
+        capture_output=True, text=True, timeout=300,
+    )
+    if result.returncode != 0:
+        sys.stderr.write(f"tabella: bootstrap failed: {result.stderr[:500]}\n")
+    else:
+        sys.stderr.write("tabella: venv ready\n")
+
+    return venv_python

{tabella_docs-2.0.1 → tabella_docs-2.0.2}/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
 
@@ -58,10 +59,6 @@ def doc_convert(
         {"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 +66,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 +97,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 +155,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)

{tabella_docs-2.0.1 → tabella_docs-2.0.2}/tabella/create.py

@@ -2,7 +2,7 @@
 
 Merged from the doc_create plugin. Dependencies (python-docx, openpyxl,
 python-pptx, weasyprint, odfpy, nano-pdf) are now installed directly in the
-main Hermes venv — the old ~/.hermes/venvs/docs subprocess pattern is removed.
+the bootstrapped per-plugin venv (PYTHON_BOOTSTRAP: scripts/setup.sh; stdio/HTTP servers exec into it on first serve)
 Builder functions import and use the libraries directly.
 """
 
@@ -18,8 +18,44 @@ from .utils import _get_output_dir, _is_in_output_dir, _resolve_output_dir
 logger = logging.getLogger(__name__)
 
 
+def _safe_url_fetcher(font_config):
+    """URL fetcher for model-supplied HTML: refuse network + host filesystem.
+
+    Only data: URIs and WeasyPrint's own font temp-file references resolve
+    — <img src>, @import and file:// against anything else raise (catalog
+    review finding 2: 'no network' must be true, not a wording promise).
+    """
+    from pathlib import Path as _P
+
+    def fetch(url, *a, **kw):
+        tmp_dir = str(getattr(font_config, "tmp_directory", "") or "")
+        if url.startswith("data:") or (
+            url.startswith("file:") and tmp_dir
+            and url[len("file://"):].startswith(_P(tmp_dir).resolve().as_posix())
+        ):
+            from weasyprint import default_url_fetcher as _default
+            return _default(url, *a, **kw)
+        raise ValueError(
+            f"blocked external URL in HTML: {url[:80]!r} — network and "
+            "host-file access are disabled; use embedded data: URIs"
+        )
+
+    return fetch
+
+
 def _css_escape(s: str) -> str:
-    return s.replace('\\', '\\\\').replace("'", "\\'")
+    # Escape string delimiters AND CSS-significant chars. CSS strings don't
+    # understand \n/\r as literal chars — convert them to the \A control
+    # sequence so an injected newline can't break out of a `content: '...'`
+    # declaration and smuggle in @font-face urls or import statements.
+    return (
+        s.replace("\\", "\\\\")
+         .replace("'", "\\'")
+         .replace("\n", "\\A ")
+         .replace("\r", "\\A ")
+         .replace("{", "\\{")
+         .replace("}", "\\}")
+    )
 
 
 # ── builder functions (direct, no subprocess) ──
@@ -265,7 +301,8 @@ def _build_pdf(content: dict, output_path: str, template: str = None, options: d
             """
 
         font_config = FontConfiguration()
-        HTML(string=html_str).write_pdf(output_path, stylesheets=[CSS(string=css_str, font_config=font_config)])
+        fetcher = _safe_url_fetcher(font_config)
+        HTML(string=html_str, url_fetcher=fetcher).write_pdf(output_path, stylesheets=[CSS(string=css_str, url_fetcher=fetcher, font_config=font_config)])
         return {"success": True, "path": output_path, "format": "pdf"}
     except Exception as e:
         return {"success": False, "error": str(e)}
@@ -483,16 +520,20 @@ def _build_pdf_from_html(content: dict, output_path: str, template: str = None,
         css_lines.append("td, th { border: 1px solid #ccc; padding: 6px; text-align: left; }")
 
         if header_text:
-            css_lines.append("@page { @top-center { content: '" + header_text.replace("'", "\\'") + "'; font-size: 9pt; color: #666; } }")
+            css_lines.append("@page { @top-center { content: '" + _css_escape(header_text) + "'; font-size: 9pt; color: #666; } }")
         if footer_text or page_numbers:
             footer_content = footer_text or ""
             if page_numbers:
                 footer_content += " Page " + ("" if not footer_text else " ") + "counter(page)"
-            css_lines.append("@page { @bottom-center { content: '" + footer_content.replace("'", "\\'") + "'; font-size: 9pt; color: #666; } }")
+            css_lines.append("@page { @bottom-center { content: '" + _css_escape(footer_content) + "'; font-size: 9pt; color: #666; } }")
 
         css_str = "\n".join(css_lines)
         font_config = FontConfiguration()
-        HTML(string=html_str).write_pdf(output_path, stylesheets=[CSS(string=css_str, font_config=font_config)])
+        fetcher = _safe_url_fetcher(font_config)
+        HTML(string=html_str, url_fetcher=fetcher).write_pdf(
+            output_path,
+            stylesheets=[CSS(string=css_str, url_fetcher=fetcher, font_config=font_config)],
+        )
         return {"success": True, "path": output_path, "format": "pdf"}
     except Exception as e:
         return {"success": False, "error": str(e)}

{tabella_docs-2.0.1 → tabella_docs-2.0.2}/tabella/read.py

@@ -1,7 +1,7 @@
 """documents.read — read documents via anydoc (primary) + LiteParse (OCR fallback).
 
 Merged from the doc_read plugin. Dependencies (firecrawl-anydoc, liteparse) are
-now installed directly in the main Hermes venv — no subprocess/venv indirection.
+now installed directly in the the bootstrapped per-plugin venv (PYTHON_BOOTSTRAP: scripts/setup.sh; stdio/HTTP servers exec into it on first serve)
 
 Architecture:
   - Office formats (DOCX, DOC, XLSX, XLSB, PPTX, PPT, ODT, ODS, ODP, RTF,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tabella-docs
-Version: 2.0.1
+Version: 2.0.2
 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
@@ -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
@@ -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
@@ -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.2}/tabella_docs.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 tabella/__init__.py
+tabella/bootstrap.py
 tabella/convert.py
 tabella/create.py
 tabella/read.py
@@ -11,4 +12,5 @@ tabella_docs.egg-info/SOURCES.txt
 tabella_docs.egg-info/dependency_links.txt
 tabella_docs.egg-info/requires.txt
 tabella_docs.egg-info/top_level.txt
+tests/test_ensure_venv_win.py
 tests/test_text_section_alias.py

tabella_docs-2.0.2/tests/test_ensure_venv_win.py

@@ -0,0 +1,125 @@
+r"""Seam test for tabella.bootstrap.ensure_venv platform handling (direct-run).
+
+Shared module serving BOTH servers (mcp_server.py + scripts/mcp_http_server.py).
+Proves, without a Windows box:
+  1. DOCS_VENV_PYTHON override short-circuits.
+  2. POSIX fast path unchanged (bin/python).
+  3. os.name=="nt": Scripts\python.exe layout, venv+pip bootstrap commands
+     mirror setup.sh (--require-hashes -r requirements-pinned.txt), success
+     and failure paths both behave.
+
+The nt seam swaps mcp_server.os for a namespace (NOT global os.name — that
+flips the shared pathlib factory to WindowsPath, uninstantiable on Linux).
+Path separators in expectations are built with the same Path arithmetic, so
+they match this platform; the real backslash layout is proven by CI on
+windows-latest.
+"""
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from types import SimpleNamespace
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from tabella import bootstrap as B  # noqa: E402
+
+
+def check(name, cond, detail=""):
+    if not cond:
+        print(f"FAIL {name}: {detail}")
+        sys.exit(1)
+    print(f"PASS {name}")
+
+
+# 1. override short-circuits
+with tempfile.TemporaryDirectory() as td:
+    fake = Path(td) / "wpython.exe"
+    fake.write_text("")
+    os.environ["DOCS_VENV_PYTHON"] = str(fake)
+    check("override", B.ensure_venv() == str(fake))
+    del os.environ["DOCS_VENV_PYTHON"]
+
+# 2. POSIX fast path: existing venv dir with bin/python returns that path
+with tempfile.TemporaryDirectory() as td:
+    os.environ["PLUGIN_DATA"] = str(Path(td) / "data")
+    venv = Path(td) / "data" / "venv"
+    (venv / "bin").mkdir(parents=True)
+    (venv / "bin" / "python").write_text("")
+    check("posix fast path", B.ensure_venv() == str(venv / "bin" / "python"))
+    del os.environ["PLUGIN_DATA"]
+
+# 2b. POSIX bootstrap seam: bash + setup.sh with the data_dir arg
+with tempfile.TemporaryDirectory() as td:
+    os.environ["PLUGIN_DATA"] = str(Path(td) / "data")
+    calls = []
+    real_run = subprocess.run
+
+    def fake_run_ok(cmd, **kw):
+        calls.append(cmd)
+        return R0(0)
+
+    class R0:
+        def __init__(self, returncode=0, stderr=""):
+            self.returncode, self.stderr = returncode, stderr
+
+    subprocess.run = fake_run_ok
+    try:
+        out = B.ensure_venv()
+    finally:
+        subprocess.run = real_run
+    want = str(Path(td) / "data" / "venv" / "bin" / "python")
+    check("posix bash cmd", calls and calls[0][0] == "bash"
+          and calls[0][1].endswith("scripts/setup.sh")
+          and calls[0][2] == str(Path(td) / "data"), f"got {calls}")
+    check("posix returns venv python", out == want, f"got {out}")
+    del os.environ["PLUGIN_DATA"]
+
+# 3. Windows seam
+with tempfile.TemporaryDirectory() as td:
+    os.environ["PLUGIN_DATA"] = str(Path(td) / "data")
+    venv_dir = Path(td) / "data" / "venv"
+    calls = []
+    real_run = subprocess.run
+    real_os = B.os
+
+    class R2:
+        def __init__(self, returncode=0, stderr=""):
+            self.returncode, self.stderr = returncode, stderr
+
+    def fake_run(cmd, **kw):
+        calls.append(cmd)
+        return R2(0) if len(calls) == 1 else R2(1, "boom")  # first ok, second fails
+
+    B.os = SimpleNamespace(name="nt", environ=os.environ)
+    subprocess.run = fake_run
+    try:
+        out = B.ensure_venv()
+    finally:
+        B.os, subprocess.run = real_os, real_run
+
+    want_python = str(venv_dir / "Scripts" / "python.exe")
+    check("nt layout", out == want_python, f"got {out}")
+    check("nt venv cmd", calls and calls[0] == [sys.executable, "-m", "venv", str(venv_dir)],
+          f"got {calls}")
+    check("nt pip cmd", len(calls) == 2 and calls[1][:3] == [want_python, "-m", "pip"]
+          and "--require-hashes" in calls[1] and "requirements-pinned.txt" in calls[1][-1],
+          f"got {calls}")
+
+    # failure at venv-creation stage: single call, still returns the path
+    calls.clear()
+
+    def fake_run2(cmd, **kw):
+        calls.append(cmd)
+        return R2(1, "no venv for you")
+
+    B.os = SimpleNamespace(name="nt", environ=os.environ)
+    subprocess.run = fake_run2
+    try:
+        out = B.ensure_venv()
+    finally:
+        B.os, subprocess.run = real_os, real_run
+    check("nt create-fail graceful", out == want_python and len(calls) == 1)
+    del os.environ["PLUGIN_DATA"]
+
+print("ensure_venv seam: ALL PASS")