PDFToMD/docs/superpowers/plans/2026-05-13-ui-folder-batch-conversion.md

UI Folder Batch Conversion Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add a minimal UI folder workflow that converts every direct-child PDF in a selected folder by sequentially invoking the existing pdf2md convert CLI.

Architecture: Keep the converter and CLI unchanged. Add deterministic folder discovery and batch command construction to src/pdf2md_ui/runner.py, then make src/pdf2md_ui/app.py run a list of CommandSpec objects sequentially on the existing worker-thread/event-queue pattern.

Tech Stack: Python 3.12, tkinter/ttk, pytest, PyInstaller, existing pdf2md_ui.runner subprocess wrapper.

---

Task 1: Runner Batch Helpers

Files:

• Modify: tests/test_ui_runner.py

• Modify: src/pdf2md_ui/runner.py

• Step 1: Write failing tests

def test_list_direct_pdf_files_returns_sorted_direct_children_only(tmp_path: Path) -> None:
    (tmp_path / "b.PDF").write_text("", encoding="utf-8")
    (tmp_path / "a.pdf").write_text("", encoding="utf-8")
    nested = tmp_path / "nested"
    nested.mkdir()
    (nested / "c.pdf").write_text("", encoding="utf-8")
    (tmp_path / "notes.txt").write_text("", encoding="utf-8")

    assert [path.name for path in list_direct_pdf_files(tmp_path)] == ["a.pdf", "b.PDF"]

def test_build_batch_convert_commands_reuses_convert_options(tmp_path: Path) -> None:
    resolved = ResolvedCommand(("pdf2md",), cwd=None, source="path")
    pdfs = [tmp_path / "a.pdf", tmp_path / "b.pdf"]

    commands = build_batch_convert_commands(
        resolved,
        pdfs,
        tmp_path / "out",
        overwrite=True,
        keep_raw=True,
        chunk_pages=5,
        gpu="auto",
        mineru_profile="safe",
    )

    assert [command.args[2] for command in commands] == [str(pdfs[0]), str(pdfs[1])]
    assert all("--chunk-pages" in command.args for command in commands)
    assert all("--mineru-profile" in command.args for command in commands)

• Step 2: Run tests to verify RED

Run: uv run pytest tests/test_ui_runner.py::test_list_direct_pdf_files_returns_sorted_direct_children_only tests/test_ui_runner.py::test_build_batch_convert_commands_reuses_convert_options -q

Expected: FAIL because the new helpers are not defined.

• Step 3: Implement minimal runner helpers

Add list_direct_pdf_files(folder) using Path.iterdir() and case-insensitive .pdf suffix matching. Add build_batch_convert_commands() that loops over the provided PDF paths and delegates to build_convert_command().

• Step 4: Run tests to verify GREEN

Run: uv run pytest tests/test_ui_runner.py -q

Expected: all UI runner tests pass.

Task 2: Tk UI Batch Execution

Files:

• Modify: src/pdf2md_ui/app.py

• Step 1: Add folder state and controls

Add input_folder_var, a path row labeled Input folder, and a Convert folder button beside the existing action buttons.

• Step 2: Add batch command startup

Implement _choose_folder(), _run_folder_convert(), and _start_command_sequence(). _run_folder_convert() validates the folder and output directory, parses chunk_pages, builds commands through the runner helper, and starts the sequence.

• Step 3: Add sequential worker behavior

Run each command synchronously on the worker thread. Emit log messages before each file starts. Stop after the first non-zero exit code. If Cancel is requested, terminate the active command and do not start later commands.

• Step 4: Run focused tests

Run: uv run pytest tests/test_ui_runner.py -q

Expected: all UI runner tests pass; UI app imports without syntax errors through test collection.

Task 3: Build and Handoff

Files:

• Modify: PROGRESS.md

• Generated ignored output: dist/pdf2md-ui.exe

• Step 1: Rebuild the UI executable

Run: uv run --group ui-build pyinstaller --clean --onefile --windowed --name pdf2md-ui src\pdf2md_ui\app.py

Expected: exit code 0 and dist\pdf2md-ui.exe exists.

• Step 2: Update progress

Record the new UI folder batch feature and verification commands in PROGRESS.md.

• Step 3: Check and commit

Run: git diff --check, git status --short, then commit only the scoped source, test, and documentation changes.