transpiler-mate-runtime 1.0.0__tar.gz

transpiler_mate_runtime-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+.task
+.venv
+__pycache__
+uv.lock
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.vscode
+site

transpiler_mate_runtime-1.0.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

transpiler_mate_runtime-1.0.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.5
+Name: transpiler-mate-runtime
+Version: 1.0.0
+Summary: Runtime discovery, execution, and CLI adapter for transpiler-mate plugins
+Project-URL: Documentation, https://terradue.github.io/transpiler-mate-runtime/
+Project-URL: Issues, https://github.com/Terradue/transpiler-mate-runtime/issues
+Project-URL: Source, https://github.com/Terradue/transpiler-mate-runtime
+Author-email: Simone Tripodi <simone.tripodi@terradue.com>, Fabrice Brito <fabrice.brito@terradue.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: click<9,>=8.4.2
+Requires-Dist: cwl-loader>=0.25.0
+Requires-Dist: loguru==0.7.3
+Requires-Dist: pydantic<3,>=2.13.4
+Requires-Dist: pyld>=3.1.0
+Requires-Dist: session-adapters>=0.5.0
+Requires-Dist: transpiler-mate-api==1.0.0

transpiler_mate_runtime-1.0.0/README.md

@@ -0,0 +1,12 @@
+# transpiler-mate-runtime
+
+[![PyPI - Version](https://img.shields.io/pypi/v/transpiler-mate-runtime.svg)](https://pypi.org/project/transpiler-mate-runtime)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/transpiler-mate-runtime.svg)](https://pypi.org/project/transpiler-mate-runtime)
+
+Runtime implementation for discovering and invoking `transpiler-mate-api` plugins.
+
+Click is confined to this distribution. Plugin packages depend on `transpiler-mate-api`, not on this package.
+
+## License
+
+[![Apache License, Version 2.0](https://img.shields.io/badge/license-Apache%20License%202.0-blue)](https://www.apache.org/licenses/LICENSE-2.0)

transpiler_mate_runtime-1.0.0/docs/examples/hello.cwl

@@ -0,0 +1,31 @@
+cwlVersion: v1.2
+class: CommandLineTool
+$namespaces:
+  s: https://schema.org/
+s:name: Hello tool
+s:description: Print a greeting
+s:dateCreated: "2026-08-24"
+s:license: https://spdx.org/licenses/Apache-2.0
+s:softwareVersion: 1.0.0
+s:softwareHelp:
+  s:name: Hello tool documentation
+  s:url: https://example.org/hello/help
+s:publisher:
+  s:name: Example organization
+s:author:
+  s:givenName: Ada
+  s:familyName: Lovelace
+  s:email: ada@example.org
+  s:affiliation:
+    s:name: Example organization
+$graph:
+  - id: hello
+    class: CommandLineTool
+    baseCommand: echo
+    inputs:
+      message:
+        type: string
+        default: Hello, world!
+        inputBinding:
+          position: 1
+    outputs: []

transpiler_mate_runtime-1.0.0/docs/explanation/architecture.md

@@ -0,0 +1,41 @@
+# Architecture
+
+`transpiler-mate-runtime` is an adapter between an API-level plugin contract
+and concrete execution concerns: package discovery, command-line parsing,
+source access, CWL loading, and logging.
+
+## API and runtime separation
+
+The `transpiler_mate` package is a native namespace shared by separately
+distributed components:
+
+- `transpiler_mate.api` defines `TranspilerPlugin`, `TranspilerContext`, option
+  models, metadata models, decorators, and plugin exceptions;
+- `transpiler_mate.runtime` discovers plugins, builds commands, and resolves
+  contexts;
+- `transpiler_mate.plugins.bundle` is the built-in plugin implementation.
+
+This separation keeps Click out of plugin packages. A plugin can depend on the
+stable API contract without coupling itself to this runtime's user interface.
+
+## Main components
+
+| Component | Responsibility |
+| --- | --- |
+| `PluginGroup` | Discover entry points and expose them as lazy Click subcommands. |
+| `plugin_loader` | Read entry-point metadata, load selected objects, and validate the plugin protocol. |
+| CLI field conversion | Derive Click parameters from a plugin's Pydantic option model. |
+| `DefaultTranspilerContextResolver` | Configure source adapters, load CWL, validate metadata, and select a process. |
+| `software_application_extractor` | Convert preserved CWL JSON-LD metadata into the API's `SoftwareApplication`. |
+| `bundle` | Serialize the complete resolved CWL document to a local file. |
+
+## Boundary of responsibility
+
+The runtime owns how a plugin is found and invoked. A plugin owns the actual
+transformation and its option schema. `cwl-loader` owns parsing and preserved
+document metadata; `session-adapters` owns scheme-specific transport behavior;
+the API package owns shared types.
+
+Keeping these responsibilities explicit makes alternate front ends possible:
+the plugin execution function itself accepts typed API objects and is not a
+Click callback.

transpiler_mate_runtime-1.0.0/docs/explanation/cwl-metadata.md

@@ -0,0 +1,47 @@
+# CWL metadata
+
+The runtime treats document metadata as part of the plugin input contract, not
+as unstructured decoration. Before any plugin executes, the metadata must
+validate as the `SoftwareApplication` model supplied by
+`transpiler-mate-api`.
+
+## Why preserved metadata is used
+
+For graph documents, `cwl-loader` parses `$graph` into
+`cwl_utils.parser.Process` objects while preserving the surrounding
+document-level metadata. The extractor reads that preserved mapping instead of
+serializing the parsed process back to YAML or JSON.
+
+This matters because parser objects represent the executable CWL structure,
+while the preserved mapping retains JSON-LD terms and the document's namespace
+context.
+
+In the currently supported loader behavior, this preserved mapping comes from
+fields surrounding `$graph`. A standalone process without a `$graph` wrapper
+does not provide the document-level metadata expected by the extractor.
+
+## Conversion process
+
+The extractor performs four operations:
+
+1. obtain the first available preserved document-level metadata mapping;
+2. make a deep copy so JSON-LD processing cannot mutate the parser's retained
+   metadata;
+3. use `$namespaces` as the expansion context and compact into an empty output
+   context, producing canonical IRIs;
+4. validate the compacted mapping as `SoftwareApplication` with aliases
+   enabled.
+
+The empty output context is intentional: model aliases can match canonical
+Schema.org IRIs without relying on whichever short prefix the source document
+chose.
+
+## Failure boundary
+
+The extractor itself distinguishes missing preserved metadata from JSON-LD and
+Pydantic validation errors. During context resolution, all loading and metadata
+extraction failures are wrapped as `PluginFailureError` saying that the source
+could not be loaded as a CWL document.
+
+Consequently, plugin code can assume that `context.metadata` is already a
+validated `SoftwareApplication`.

transpiler_mate_runtime-1.0.0/docs/explanation/index.md

@@ -0,0 +1,8 @@
+# Explanation
+
+Explanation pages describe why the runtime is structured as it is and how its
+parts relate.
+
+- [Architecture](architecture.md)
+- [Plugin lifecycle](plugin-lifecycle.md)
+- [CWL metadata](cwl-metadata.md)

transpiler_mate_runtime-1.0.0/docs/explanation/plugin-lifecycle.md

@@ -0,0 +1,47 @@
+# Plugin lifecycle
+
+A plugin moves through discovery, command construction, context resolution,
+and execution. Each stage is delayed until it is needed.
+
+## 1. Discovery
+
+The root Click group queries installed metadata for the
+`transpiler_mate.plugins` entry-point group. It sorts commands by name and
+detects duplicate registrations without importing plugin modules.
+
+This keeps root help responsive and prevents one unused plugin's import cost
+from affecting every invocation.
+
+## 2. Loading and command construction
+
+When a command is requested, its entry point is loaded and checked against the
+`TranspilerPlugin` protocol. The entry-point name and plugin name must agree.
+
+The runtime then reads `plugin.options_model.model_fields` and combines the
+derived plugin options with the common `SOURCE` argument and connection
+options. The generated command is cached.
+
+## 3. Option validation
+
+Click parses individual values. The runtime omits untouched, non-required
+defaults from the input dictionary so Pydantic can run default factories and
+model-level logic normally. It then validates the complete options model with
+both aliases and Python field names enabled.
+
+No source is loaded when showing plugin help or when option validation fails.
+
+## 4. Context resolution
+
+Only immediately before execution does the command create a resolver. The
+resolver mounts transport adapters, loads the CWL document, validates its
+Schema.org metadata, and optionally selects a process.
+
+The resulting `TranspilerContext` gives every plugin the same normalized view
+of its input regardless of whether the source was a local path, HTTP URL, or
+OCI location.
+
+## 5. Execution and reporting
+
+The runtime calls `plugin.execute(context, options)`. It distinguishes expected
+result failures from unexpected execution errors, logs a success or failure
+banner, and always reports elapsed and finish times once execution has begun.

transpiler_mate_runtime-1.0.0/docs/how-to/access-remote-sources.md

@@ -0,0 +1,59 @@
+# Access remote sources
+
+Every plugin command accepts the same runtime connection options. Place them
+after the plugin name and before or after other plugin options:
+
+```console
+transpiler-mate <plugin> [RUNTIME_OPTIONS] [PLUGIN_OPTIONS] SOURCE
+```
+
+## Authenticate to HTTP and HTTPS
+
+Set a bearer token:
+
+```console
+export OAUTH2_BEARER="your-token"
+transpiler-mate <plugin> [PLUGIN_OPTIONS] https://example.org/tool.cwl
+```
+
+Or pass it directly:
+
+```console
+transpiler-mate <plugin> \
+  --oauth2-bearer "your-token" \
+  [PLUGIN_OPTIONS] \
+  https://example.org/tool.cwl
+```
+
+Without a token, the runtime uses a standard HTTP adapter. With a token, it
+mounts a bearer-authentication adapter for both HTTP and HTTPS.
+
+## Authenticate to OCI
+
+Prefer environment variables for credentials:
+
+```console
+export OCI_HOSTNAME="registry.example.org"
+export OCI_USERNAME="your-user"
+export OCI_PASSWORD="your-password"
+transpiler-mate <plugin> [PLUGIN_OPTIONS] oci://namespace/tool:tag
+```
+
+The equivalent command options are `--oci-hostname`, `--oci-username`, and
+`--oci-password`.
+
+## Select a process in a remote document
+
+Append a fragment to the source:
+
+```console
+transpiler-mate <plugin> [PLUGIN_OPTIONS] \
+  oci://namespace/workflow:tag#main
+```
+
+See [Select a process](select-a-process.md) for the selection behavior.
+
+!!! warning
+    Command-line secrets may be recorded in shell history and visible to other
+    local processes. Prefer the supported environment variables or your
+    platform's secret injection facility.

transpiler_mate_runtime-1.0.0/docs/how-to/bundle-a-cwl-document.md

@@ -0,0 +1,64 @@
+# Bundle a CWL document
+
+Use the built-in `bundle` plugin to load a CWL document and serialize the
+resolved document to a local file.
+
+## Bundle a local document
+
+Pass the destination with `--output` and the source as the final argument:
+
+```console
+transpiler-mate bundle --output build/workflow.cwl workflow.cwl
+```
+
+Parent directories of the output are created automatically.
+
+## Bundle an HTTP or HTTPS document
+
+Use the source URL directly:
+
+```console
+transpiler-mate bundle \
+  --output build/workflow.cwl \
+  https://example.org/workflows/workflow.cwl
+```
+
+For a protected endpoint, add a bearer token through the environment:
+
+```console
+export OAUTH2_BEARER="your-token"
+transpiler-mate bundle \
+  --output build/workflow.cwl \
+  https://example.org/workflows/workflow.cwl
+```
+
+You can also pass `--oauth2-bearer`, but an environment variable is less likely
+to expose the token in shell history or process listings.
+
+## Bundle an OCI document
+
+Configure the registry connection and pass an `oci://` source:
+
+```console
+export OCI_HOSTNAME="registry.example.org"
+export OCI_USERNAME="your-user"
+export OCI_PASSWORD="your-password"
+transpiler-mate bundle \
+  --output build/workflow.cwl \
+  oci://namespace/workflow:tag
+```
+
+The exact OCI path semantics are implemented by the installed
+`session-adapters` package. The runtime supplies the hostname and credentials
+to its OCI adapter.
+
+## Check the result
+
+A successful invocation logs `SUCCESS` and exits with status `0`. Expected
+input or output failures log `FAILURE` or `ERROR` and exit with status `1`; CLI
+usage errors exit with status `2`. See [Errors and exit codes](../reference/errors-and-exit-codes.md).
+
+The plugin serializes the complete loaded document. Adding a `#process-id` to
+the source selects a process in the context for plugins that use
+`resolved_process`; it does not make the built-in `bundle` plugin extract that
+process from the document.

transpiler_mate_runtime-1.0.0/docs/how-to/index.md

@@ -0,0 +1,8 @@
+# How-to guides
+
+How-to guides provide task-oriented instructions for common runtime jobs.
+
+- [Bundle a CWL document](bundle-a-cwl-document.md)
+- [Select a process](select-a-process.md)
+- [Access remote sources](access-remote-sources.md)
+- [Register a plugin](register-a-plugin.md)

transpiler_mate_runtime-1.0.0/docs/how-to/register-a-plugin.md

@@ -0,0 +1,72 @@
+# Register a plugin
+
+A plugin distribution becomes a `transpiler-mate` subcommand by registering a
+`TranspilerPlugin` object in the `transpiler_mate.plugins` entry-point group.
+
+## 1. Define its options and execution function
+
+Use the API package's decorator and a Pydantic model:
+
+```python
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+from transpiler_mate.api import TranspilerContext, transpiler_plugin
+
+
+class ExampleOptions(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    output: Path = Field(description="Destination file")
+    verbose: bool = Field(default=False, description="Enable verbose output")
+
+
+@transpiler_plugin(
+    name="example",
+    description="Run the example transpiler.",
+    options_model=ExampleOptions,
+)
+def plugin(context: TranspilerContext, options: ExampleOptions) -> None:
+    source = context.source
+    process = context.resolved_process
+    # Perform the transformation and write options.output.
+```
+
+The runtime converts model fields into Click options. Required fields become
+required options, field descriptions become help text, and optional Boolean
+fields become `--name/--no-name` flag pairs.
+
+## 2. Register the entry point
+
+If the module above is `example_plugin/__init__.py`, add this to the plugin
+package's `pyproject.toml`:
+
+```toml
+[project.entry-points."transpiler_mate.plugins"]
+example = "example_plugin:plugin"
+```
+
+The entry-point name must equal the plugin's `name`. The runtime rejects a
+mismatch when the command is requested.
+
+## 3. Install and verify the plugin
+
+Install the plugin distribution into the same environment as the runtime:
+
+```console
+python -m pip install -e /path/to/example-plugin
+transpiler-mate --help
+transpiler-mate example --help
+```
+
+The root help should list `example`, while the plugin help should show
+`SOURCE`, the shared connection options, `--output`, and the Boolean flag pair.
+
+## 4. Report failures deliberately
+
+Raise the API's `PluginFailureError` for an expected inability to produce a
+result. Raise `PluginExecutionError` for an unexpected technical failure. Both
+produce status `1`, but the runtime logs a traceback only for the latter.
+
+Other `PluginError` subclasses are presented as Click errors. See
+[Errors and exit codes](../reference/errors-and-exit-codes.md).

transpiler_mate_runtime-1.0.0/docs/how-to/select-a-process.md

@@ -0,0 +1,31 @@
+# Select a process
+
+Append `#<process-id>` to a source location when a plugin needs one process
+from a CWL graph:
+
+```console
+transpiler-mate <plugin> [PLUGIN_OPTIONS] workflow.cwl#main
+```
+
+The fragment is handled by the runtime rather than sent to the source loader.
+The runtime loads `workflow.cwl`, searches the resulting process or process
+list for `main`, and exposes the match as `context.resolved_process`.
+
+The same syntax applies to remote sources:
+
+```console
+transpiler-mate <plugin> [PLUGIN_OPTIONS] \
+  https://example.org/workflow.cwl#main
+```
+
+If the ID does not exist, the runtime reports the IDs that are available and
+exits with status `1`. A trailing `#` with no ID is an execution error.
+
+When a loaded document contains multiple processes and no fragment is given,
+the runtime logs a warning and leaves `resolved_process` unset. The full graph
+remains available through `context.document`.
+
+!!! note
+    The built-in `bundle` plugin writes `context.document`, not
+    `context.resolved_process`. Process selection is therefore useful only for
+    plugins that explicitly consume the selected process.