Expand structured output contracts

Author: jmchilton

HISTORY.rst

@@ -9,6 +9,8 @@ History
 0.75.42.dev0
 ---------------------
 
+* Add structured CLI metadata and output schema exports, validate Planemo JSON
+  outputs, and write full merged test reports.
 
 ---------------------
 0.75.41 (2026-03-19)

docs/_running_external.rst

@@ -313,8 +313,20 @@ You can specify a different location with the ``--output_directory`` option:
 
     $ planemo invocation_download INVOCATION_ID --profile tutorial_profile --output_directory ./my_outputs
 
-The command also supports ``--output_json`` to write a JSON file containing
-metadata about the downloaded outputs.
+The command also supports ``--output_json`` to write a JSON manifest containing
+metadata about the downloaded outputs:
+
+::
+
+    $ planemo invocation_download INVOCATION_ID --profile tutorial_profile --output_directory ./my_outputs --output_json ./my_outputs/manifest.json
+
+The manifest includes the invocation ID, output directory, downloaded outputs,
+and outputs that were not downloaded. Optional workflow outputs that are absent
+are reported as ``skipped``; required outputs that are absent while missing
+outputs are ignored are reported as ``missing``. Paths in the manifest are
+relative to ``--output_directory`` by default. Use
+``--output_json_path_type absolute`` when absolute paths are more useful for
+automation.
 
 
 Exporting invocations as archives

docs/_writing_test_reports.rst

@@ -5,4 +5,12 @@ in certain `continuous integration`_ environments. See ``planemo test --help`` f
 more options, as well as the ``test_reports`` `command
 <http://planemo.readthedocs.io/en/latest/commands.html#test-reports-command>`__.
 
+The machine-readable JSON report written by ``--test_output_json`` uses the
+Planemo test report shape: a top-level ``version``, ``tests``, optional
+``summary``, and optional ``exit_code``. ``test_reports`` validates this JSON
+before rendering derived reports. ``merge_test_reports`` also validates each
+input report and writes the same full report shape, including recalculated
+``summary`` and ``exit_code`` fields. Older reports without ``summary`` are
+still accepted and summarized during rendering.
+
 .. _continuous integration: https://en.wikipedia.org/wiki/Continuous_integration

docs/commands.rst

@@ -11,6 +11,7 @@ documentation describes these commands.
 .. include:: commands/ci_find_repos.rst
 .. include:: commands/ci_find_tools.rst
 .. include:: commands/ci_setup.rst
+.. include:: commands/cli_metadata.rst
 .. include:: commands/clone.rst
 .. include:: commands/conda_build.rst
 .. include:: commands/conda_env.rst
@@ -41,6 +42,7 @@ documentation describes these commands.
 .. include:: commands/mulled_init.rst
 .. include:: commands/normalize.rst
 .. include:: commands/open.rst
+.. include:: commands/output_schema.rst
 .. include:: commands/profile_create.rst
 .. include:: commands/profile_delete.rst
 .. include:: commands/profile_job_config_init.rst

docs/commands/cli_metadata.rst

@@ -0,0 +1,23 @@
+
+``cli_metadata`` command
+========================================
+
+This section is auto-generated from the help text for the planemo command
+``cli_metadata``. This help message can be generated with ``planemo cli_metadata
+--help``.
+
+**Usage**::
+
+    planemo cli_metadata [OPTIONS]
+
+**Help**
+
+Export structured metadata for Planemo CLI commands.
+**Options**::
+
+
+      --format [json]     [default: json]
+      --command TEXT      Only export metadata for the selected command.
+      --include-internal  Include internal commands not documented as public API.
+      --help              Show this message and exit.
+    

docs/commands/invocation_download.rst

@@ -28,12 +28,16 @@ through Galaxy's web interface or through planemo.
                                       Where to store outputs of a 'run' task.
       --output_json FILE              Where to store JSON dictionary describing
                                       outputs of a 'run' task.
+      --output_json_path_type [relative|absolute]
+                                      Path style to use in the output JSON manifest.
+                                      [default: relative]
       --profile TEXT                  Name of profile (created with the
                                       profile_create command) to use with this
                                       command.
       --galaxy_url TEXT               Remote Galaxy URL to use with external Galaxy
                                       engine.
       --galaxy_user_key TEXT          User key to use with external Galaxy engine.
-      --ignore_missing_output         Ignore missing output files
+      --ignore_missing_output / --no_ignore_missing_output
+                                      Ignore missing output files
       --help                          Show this message and exit.
     

docs/commands/output_schema.rst

@@ -0,0 +1,23 @@
+
+``output_schema`` command
+========================================
+
+This section is auto-generated from the help text for the planemo command
+``output_schema``. This help message can be generated with ``planemo output_schema
+--help``.
+
+**Usage**::
+
+    planemo output_schema [OPTIONS]
+
+**Help**
+
+Export JSON Schemas for Planemo machine-readable outputs.
+**Options**::
+
+
+      --format [json]                 [default: json]
+      --schema [invocation-download-manifest|run-outputs|test-report]
+                                      Only export one schema.
+      --help                          Show this message and exit.
+    

docs/commands/test.rst

@@ -48,8 +48,8 @@ please careful and do not try this against production Galaxy instances.
                                       produced with the same set of tool ids
                                       previously.
       --test_index INTEGER            Index(es) of specific test(s) to run
-                                      (0-based). Can be specified multiple times
-                                      (e.g., --test_index 0 --test_index 2) to run
+                                      (1-based). Can be specified multiple times
+                                      (e.g., --test_index 1 --test_index 3) to run
                                       specific tests. If not specified, all tests
                                       are run.
       --polling_backoff INTEGER       Poll resources with an increasing interval

docs/planemo.commands.rst

@@ -36,6 +36,14 @@ planemo.commands.cmd\_ci\_setup module
    :show-inheritance:
    :undoc-members:
 
+planemo.commands.cmd\_cli\_metadata module
+------------------------------------------
+
+.. automodule:: planemo.commands.cmd_cli_metadata
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 planemo.commands.cmd\_clone module
 ----------------------------------
 
@@ -284,6 +292,14 @@ planemo.commands.cmd\_open module
    :show-inheritance:
    :undoc-members:
 
+planemo.commands.cmd\_output\_schema module
+-------------------------------------------
+
+.. automodule:: planemo.commands.cmd_output_schema
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 planemo.commands.cmd\_profile\_create module
 --------------------------------------------
 

docs/planemo.rst

@@ -48,6 +48,14 @@ planemo.cli module
    :show-inheritance:
    :undoc-members:
 
+planemo.cli\_metadata module
+----------------------------
+
+.. automodule:: planemo.cli_metadata
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 planemo.conda module
 --------------------
 
@@ -160,6 +168,22 @@ planemo.options module
    :show-inheritance:
    :undoc-members:
 
+planemo.output\_models module
+-----------------------------
+
+.. automodule:: planemo.output_models
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+planemo.output\_schemas module
+------------------------------
+
+.. automodule:: planemo.output_schemas
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 planemo.runnable module
 -----------------------