Interest in library-fying and perhaps extending some of the validation in CLI.py?

[geoffjentry]

A while back we wrote some code built on top of miniwdl to help us manage automation of WDL workflow running in a larger platform. Most of it involved introspecting a WDL to validate inputs in an inputs JSON & similar functionality for outputs JSON to facilitate automated output handling. I've been meaning to open source this work for a while, but realized miniwdl could make more sense as a home.

And then I realized that CLI.py includes similar functionality already.

I'm proposing I put together a contribution including:

1. First identifying any areas of our code providing enhancement over what miniwdl is already doing
2. Putting all of this a location that's more accessible/documented for use cases like we had (Specific location TBD, let me know if you have preferences?)
3. Updating CLI.py as appropriate

[mlin]

@geoffjentry I'm moving miniwdl maintenance toward "supervised FSD" with AI and this sounds like a ripe opportunity to me. You or I could take your tool, plop it into a temp subdirectory of this repo, fire up Claude/Codex/Gemini, tell it to read AGENTS.md, CLI.py, and the tool, and come back to us with a plan along the lines of your 123. It should give us a solid starting point at the least. WDYT?

[geoffjentry]

@mlin I think that at least for the portion that's just taking what's currently baked into CLI.py and pulling it out that can work. I'll try to set that up.

For our custom code - the process of evaluating if there's any useful functionality beyond what's currently in miniwdl I want to do by hand as I'll also need to tease out some proprietary bits that we can't contribute, and an AI bot isn't going to understand. But it'll be easier with the current stuff pulled out, so can cross that bridge second.

So new order of operations:

1. I will submit a plan to pull out validation code from CLI.py, stick it somewhere generally useful, and add docs
2. After that's done, I'll evaluate our custom code in context of the results of step 1 -> this is a branch point so we'll see what happens there.

[geoffjentry]

@mlin I'm skeptical this is quite right and/or fully baked in terms of teasing apart validation from CLI.py but I think a reasonable next step would be getting this into a branch. It was unclear to me if you had some sort of higher level automation processing these plans - if not I can just run it and go from there:

Plan: Extract Validation Logic from CLI.py into WDL/Validation.py

Context

Users of miniwdl as a library need access to pre-execution validation logic that currently lives in WDL/CLI.py. This includes validating inputs against WDL types, checking required inputs are supplied, and validating file/directory paths. Currently these are interleaved with CLI-specific concerns (argparse, stdin, --empty/--none flags, name=value parsing, help printing). Extracting the non-CLI validation into a library module lets programmatic users validate inputs without going through the CLI.

New File: WDL/Validation.py

Following the WDL/Zip.py pattern: imports only from sibling submodules, not from __init__.py. Lazy imports for values_from_json/values_to_json to avoid circular dependencies. No re-exports from __init__.py — users access via WDL.Validation.*.

Functions to create

1. validate_input_path(path, directory, downloadable=None, root="/") -> str

• Extracted from validate_input_path() (CLI.py:1295-1331)
• Logic unchanged; fix latent variable shadowing bug (root loop var renamed to root_dir)

2. validate_input_paths(input_env, downloadable=None, root="/") -> Env.Bindings[Value.Base]

• New convenience: applies validate_input_path to every File/Directory in an Env.Bindings via Value.rewrite_env_paths

3. check_required_inputs(target, input_env) -> None

• Extracted from CLI.py:1075-1081
• Raises Error.InputError listing missing input names
• Uses lazy from . import values_to_json to avoid circular import

4. validate_inputs(target, input_json, *, check_required=True, downloadable=None, root="/", namespace="") -> Env.Bindings[Value.Base]

• High-level convenience combining values_from_json + validate_input_paths + check_required_inputs
• Uses lazy from . import values_from_json
• namespace defaults to "" — caller passes target.name for workflows if their JSON uses Cromwell-style namespaced keys

All functions get full type annotations and RST-style docstrings.

Changes to WDL/__init__.py

None. Following the Zip.py pattern — Validation is accessed as WDL.Validation.

Changes to docs/WDL.rst

Add a Validation section (following the Zip pattern) so Sphinx autodoc generates API docs from the docstrings:

Validation
----------
.. automodule:: WDL.Validation
   :members:

Changes to WDL/CLI.py

Import

Add Validation to the existing from . import (...) block (CLI.py:21-42).

Replace validate_input_path() usage

• In runner_input_json_file (lines 1144-1149): replace Value.rewrite_env_paths(...) block with ans = Validation.validate_input_paths(ans, downloadable, root)
• In runner_input_value (line 1246): call Validation.validate_input_path(...) instead
• Delete the validate_input_path function definition (lines 1295-1331)

Replace required inputs check (lines 1075-1081)

if check_required:
    try:
        Validation.check_required_inputs(target, input_env)
    except Error.InputError:
        runner_input_help(target)  # CLI-specific: show help before error
        raise

What stays in CLI.py (unchanged)

• runner_exe() — resolve which workflow/task to run
• runner_input_value() — CLI string-to-Value parsing
• runner_input_help() — stderr help display
• runner_input_completer() — argcomplete
• --empty / --none handling in runner_input()
• name=value CLI input parsing in runner_input()
• make_read_source() — HTTP download + --no-outside-imports
• runner_input_json_file() — file/stdin reading (but delegates path validation to Validation)
• All configuration validation in runner()
• is_constant_expr(), runner_env_override(), runner_standard_output()

New File: tests/test_validation.py

Unit tests for the extracted functions:

• validate_input_path: existing file; nonexistent file (error); file outside root (error); downloadable URI passthrough; directory with bad symlinks (error)
• validate_input_paths: env with valid File values; env with invalid paths (error)
• check_required_inputs: all supplied (ok); missing inputs (error with names)
• validate_inputs: valid JSON end-to-end; missing required with check_required=True (error); missing required with check_required=False (ok); type mismatch (error)

Tests use WDL.parse_document() to create synthetic WDL documents without loading from disk.

Verification

1. Lint: ruff check --fix WDL/Validation.py WDL/CLI.py && ruff format WDL/Validation.py WDL/CLI.py
2. Type check: mypy WDL/Validation.py WDL/CLI.py
3. Targeted tests: python3 -m pytest -xvs tests/test_validation.py
4. Existing tests: python3 -m pytest -xvs tests/test_input_template.py tests/test_7runner.py
5. Quick test suite: make qtest

[mlin]

@geoffjentry It looks like a fine starting point to me -- I'd just feed back that Validation isn't a specific enough module name in the context of the whole project.

I thought I should mention too that one can currently import WDL.CLI to use various helper functions in there directly (example). However, at over 2K LOC it's obvious that CLI.py is long overdue to be refactored/broken up, so I support that!

[geoffjentry]

@mlin I finally had a chance (and the spare Claude quota 😅) to dive into this more. I let Claude do a big compare and contrast against what we had vs what was already baked into CLI (both as less-than-documented functions, but also embedded inside there functions). Not a surprise but there was less novel functionality from our original library than I originally thought. Since I wanted to play around with superpowers anyways I had it set up a design spec & plan to pull stuff out to independent functions, get CLI using it, and then adding a few enhancements from our library (the one in particular I remember was an optional/pluggable capability to detect non-local input files existence status)

I'll include the superpowers spec & plan below. I've got the whole thing ready to go & can open a PR, or if you want to push back I may as well not 😄

2026-03-12-input-processing-api-design.md

2026-03-12-input-processing-api.md