sysml-windtrader 0.2.1__py3-none-any.whl

sysml_windtrader-0.2.1.dist-info/METADATA

@@ -0,0 +1,238 @@
+Metadata-Version: 2.5
+Name: sysml-windtrader
+Version: 0.2.1
+Summary: Python wrapper around windtrader-java for SysML v2 parse-only validation.
+Author: Westfall-io
+License: MIT License
+        
+        Copyright (c) 2026 chriscox-westfall
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: coverage[toml]>=7.6; extra == 'dev'
+Requires-Dist: interrogate>=1.7; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: python-semantic-release>=10.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# windtrader
+
+**windtrader** is a lightweight Python wrapper around the `windtrader-java` SysML v2 validator.
+It provides a simple, scriptable way to validate SysML v2 textual syntax from Python while
+delegating all grammar authority to the official Java-based validator.
+
+This project is intentionally *parse-only*: it validates syntax, reports diagnostics, and
+(optionally) echoes parsed output, but does **not** perform semantic resolution or model linking.
+
+---
+
+## Status
+
+![CI](https://github.com/Westfall-io/windtrader/actions/workflows/ci.yml/badge.svg)
+![Coverage](https://codecov.io/gh/Westfall-io/windtrader/branch/main/graph/badge.svg)
+![Docstrings](https://img.shields.io/badge/docstrings-interrogate-success)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/github/license/Westfall-io/windtrader)
+
+---
+
+## Key Features
+
+- ✅ Validates SysML v2 textual syntax using a pinned Java validator
+- 🧩 Thin, explicit Python API (no hidden model interpretation)
+- 📦 Automatic download and caching of the validator JAR
+- 🧪 Designed for CI, generators, and downstream tooling
+- 🔐 Stable exit-code contract from Java → Python
+
+---
+
+## Installation
+
+```bash
+pip install sysml-windtrader
+```
+
+Or for development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Java **must** be available on your system (CI uses Temurin JDK).
+
+---
+
+## Command-Line Usage
+
+```bash
+echo "part { attribute mass; }" | windtrader           # validate (default: check)
+echo "part { attribute mass; }" | windtrader export     # print element JSON graph
+```
+
+Subcommands:
+
+```text
+check    (default) parse-validate SysML text
+echo     print the normalized/echoed representation
+export   parse SysML and print the SysMLv2 element JSON graph (API shape)
+```
+
+Options:
+
+```text
+--version            Show windtrader package version
+--java-version       windtrader-java version to use (default: 0.2.0)
+--timeout            Subprocess timeout (default: 10s for check/echo, 120s for export)
+```
+
+The CLI forwards stdout/stderr directly from the Java tool and exits with the same exit code.
+
+---
+
+## Python API
+
+> **0.2.0 rename:** `windtrader.validator` (module) / `WindtraderValidator` /
+> `ValidationResult` are now `windtrader.client` / `WindtraderClient` /
+> `CommandResult`. The module drives `check`, `echo`, and now `export`, so the
+> old "validator" name was misleading. Update imports from `windtrader.validator`
+> to `windtrader.client` and the class/type names accordingly.
+>
+> ```python
+> # before (0.1.x)
+> from windtrader.validator import WindtraderValidator, ValidationResult
+> # after (0.2.0)
+> from windtrader.client import WindtraderClient, CommandResult
+> ```
+
+### Basic validation
+
+```python
+from windtrader import validate
+
+result = validate("part { attribute mass; }")
+
+if result.ok:
+    print("Valid SysML")
+else:
+    print("Invalid:", result.stderr)
+```
+
+### Client object
+
+```python
+from windtrader import WindtraderClient
+
+client = WindtraderClient(version="0.2.0")
+res = client.validate("part { attrib mass; }")
+
+print(res.exit_code)  # 0 = valid, 2 = syntax error, 3 = runtime error
+```
+
+### Export
+
+```python
+from windtrader import export
+
+res = export("part { attribute mass; }")
+
+if res.ok:
+    print(res.stdout)  # SysMLv2 element JSON graph (array of API-shaped elements)
+else:
+    print("Failed:", res.stderr)
+```
+
+### CommandResult
+
+Returned objects include:
+
+- `ok`: boolean success flag
+- `exit_code`: Java exit code
+- `stdout` / `stderr`: raw tool output
+- `jar_path`: cached JAR location
+- `duration_s`: execution time
+- `is_invalid_syntax`
+- `is_runtime_error`
+
+---
+
+## Exit Code Contract
+
+The Java validator defines:
+
+| Exit Code | Meaning            |
+|----------:|--------------------|
+| 0         | Valid syntax       |
+| 2         | Invalid SysML      |
+| 3         | Runtime error      |
+
+Python preserves these codes exactly.
+
+---
+
+## Configuration
+
+Environment variables:
+
+- `WINDTRADER_CACHE_DIR` – override JAR cache directory
+- `WINDTRADER_JAVA_REPO` – override GitHub repo for JAR downloads
+- `WINDTRADER_JAVA_STABLE_ASSET` – explicit asset URL (optional)
+
+---
+
+## Design Philosophy
+
+- **Grammar is authoritative**: validation truth lives in Java
+- **Python is orchestration only**
+- **No silent fallbacks**
+- **Reproducible CI behavior**
+
+This makes `windtrader` suitable as a foundation for:
+
+- Code generators
+- Corpus analysis
+- Model-building libraries
+- CI validation gates
+
+---
+
+## Relationship to Other Projects
+
+`windtrader` is designed to act as the validation backbone for higher-level SysML tooling,
+including programmatic builders and corpus-driven API generation pipelines.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+---
+
+## Contributing
+
+Pull requests welcome. Please ensure:
+
+- CI passes
+- Docstring coverage remains high
+- Backend version bumps are intentional

sysml_windtrader-0.2.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+windtrader/__init__.py,sha256=eYOmz4YYtPqXmVALpCZlo1DT2mGJ1POdD3GBbpPC_kI,288
+windtrader/_jars.py,sha256=abVotYnUIU-qh-QwUxonFK2vRJzwYLN1cKLGj7_5Kj0,5613
+windtrader/cli.py,sha256=k6Wfk6NtoyvsnZQcXkFxqIx5CFxNF1EKTdO7ECxfIxc,4524
+windtrader/client.py,sha256=JGSqbIrAyRP1Lk48oorKfnF2kbbL1G7ReBGZQzPuyds,8411
+sysml_windtrader-0.2.1.dist-info/METADATA,sha256=lkBKn4T15O4SEwUluK0QkH-qYafVy1MWRYCSIyea-Ho,6717
+sysml_windtrader-0.2.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+sysml_windtrader-0.2.1.dist-info/entry_points.txt,sha256=GKbsRIUmxzbnKnE6wQF4J3dEBuPfXX2x67gEEy2SFds,51
+sysml_windtrader-0.2.1.dist-info/licenses/LICENSE,sha256=4VyG3BfBk1RobrJx73i9jLX9WX1TqNHcPdNbFgOZA6o,1074
+sysml_windtrader-0.2.1.dist-info/RECORD,,

sysml_windtrader-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

sysml_windtrader-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+windtrader = windtrader.cli:main

sysml_windtrader-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chriscox-westfall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

windtrader/__init__.py

@@ -0,0 +1,19 @@
+from .client import (
+    CommandResult,
+    WindtraderClient,
+    echo,
+    export,
+    validate,
+    validate_across_versions,
+)
+
+__all__ = [
+    "CommandResult",
+    "WindtraderClient",
+    "echo",
+    "export",
+    "validate",
+    "validate_across_versions",
+]
+
+__version__ = "0.2.0"

windtrader/_jars.py

@@ -0,0 +1,166 @@
+"""
+windtrader._jars
+
+Utilities for locating, downloading, and caching the `windtrader-java` validator JAR.
+
+This module is intentionally dependency-free (stdlib only) so the Python wrapper can
+remain lightweight while still fetching the pinned Java validator from GitHub Releases.
+
+Key behavior:
+- Determine a local cache directory (default: `~/.cache/windtrader`, overridable via env).
+- Resolve the expected JAR cache path for a requested version.
+- Attempt to download the JAR from a small set of candidate release URLs.
+- Cache the JAR on disk so subsequent validations do not hit the network.
+
+Environment variables:
+- WINDTRADER_CACHE_DIR:
+    Override the root cache directory where downloaded JARs are stored.
+- WINDTRADER_JAVA_REPO:
+    Override the GitHub repo used to fetch JARs (default: "Westfall-io/windtrader-java").
+- WINDTRADER_JAVA_STABLE_ASSET:
+    Optional: a fully-qualified URL to a stable asset (first-choice download target).
+"""
+
+from __future__ import annotations
+
+import os
+import urllib.request
+from pathlib import Path
+
+DEFAULT_REPO = "Westfall-io/windtrader-java"
+DEFAULT_VERSION = "0.2.0"  # Default windtrader-java backend version when none is provided.
+
+
+def _cache_dir() -> Path:
+    """
+    Return the base cache directory for windtrader artifacts.
+
+    By default this is `~/.cache/windtrader` on Unix-like systems. Users can override
+    the location using the `WINDTRADER_CACHE_DIR` environment variable.
+
+    Returns:
+        Path: Absolute path to the cache base directory.
+    """
+    base = os.environ.get("WINDTRADER_CACHE_DIR")
+    if base:
+        return Path(base).expanduser().resolve()
+    return Path.home() / ".cache" / "windtrader"
+
+
+def _jar_cache_path(version: str) -> Path:
+    """
+    Return the expected local cache path for the given windtrader-java version.
+
+    Args:
+        version: windtrader-java version string (e.g. "0.1.1").
+
+    Returns:
+        Path: Path where the JAR should be stored in the cache.
+    """
+    return _cache_dir() / "jars" / f"windtrader-java-{version}.jar"
+
+
+def _download(url: str, dest: Path) -> None:
+    """
+    Download a URL to the destination path atomically.
+
+    The download is written to a temporary file first and then replaced into place.
+    This helps avoid leaving partial/corrupt JARs in the cache if the process is interrupted.
+
+    Args:
+        url: The URL to download.
+        dest: Destination path for the downloaded content.
+
+    Raises:
+        URLError / HTTPError: If the network request fails.
+        OSError: If writing to disk fails.
+    """
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_suffix(dest.suffix + ".tmp")
+
+    req = urllib.request.Request(
+        url,
+        headers={"User-Agent": "windtrader/0.1.0 (+https://github.com/Westfall-io/windtrader)"},
+    )
+
+    with urllib.request.urlopen(req) as r, open(tmp, "wb") as f:
+        f.write(r.read())
+
+    tmp.replace(dest)
+
+
+def _candidate_urls(version: str) -> list[str]:
+    """
+    Build a prioritized list of candidate GitHub Release URLs for a given version.
+
+    This wrapper expects the Java validator JAR to be published as an asset on GitHub Releases.
+    Because tag/asset conventions can vary, we try a small fallback list.
+
+    Candidates include:
+    - Optional stable asset URL (env: WINDTRADER_JAVA_STABLE_ASSET)
+    - Tag formatted as `v{version}` with asset named `windtrader-java-{version}.jar`
+    - Tag formatted as `{version}` with the same asset name
+    - `releases/latest/download` as a fallback (still using the versioned filename)
+
+    Args:
+        version: windtrader-java version string (e.g. "0.1.1").
+
+    Returns:
+        list[str]: Candidate URLs to try in order.
+    """
+    repo = os.environ.get("WINDTRADER_JAVA_REPO", DEFAULT_REPO)
+
+    stable_asset = os.environ.get("WINDTRADER_JAVA_STABLE_ASSET", "").strip()
+
+    urls: list[str] = []
+    if stable_asset:
+        urls.append(stable_asset)
+
+    urls.append(
+        f"https://github.com/{repo}/releases/download/v{version}/windtrader-java-{version}.jar"
+    )
+    urls.append(
+        f"https://github.com/{repo}/releases/download/{version}/windtrader-java-{version}.jar"
+    )
+    urls.append(f"https://github.com/{repo}/releases/latest/download/windtrader-java-{version}.jar")
+
+    return urls
+
+
+def get_jar_path(version: str) -> Path:
+    """
+    Ensure the requested windtrader-java JAR is present locally and return its path.
+
+    If the JAR is already present in the local cache and appears non-empty, it is reused.
+    Otherwise, the function attempts to download the JAR from GitHub Release URLs and
+    caches it.
+
+    Args:
+        version: windtrader-java version to fetch. If blank/None-like, DEFAULT_VERSION is used.
+
+    Returns:
+        Path: Local filesystem path to the cached JAR.
+
+    Raises:
+        RuntimeError: If the JAR could not be downloaded from any candidate URL.
+    """
+    version = (version or "").strip() or DEFAULT_VERSION
+    dest = _jar_cache_path(version)
+
+    if dest.exists() and dest.stat().st_size > 0:
+        return dest
+
+    last_err: Exception | None = None
+    tried: list[str] = []
+
+    for url in _candidate_urls(version):
+        tried.append(url)
+        try:
+            _download(url, dest)
+            if dest.exists() and dest.stat().st_size > 0:
+                return dest
+        except Exception as e:  # noqa: BLE001 - intentionally try any download failure against the next candidate URL
+            last_err = e
+
+    msg = "Failed to download windtrader-java jar.\nTried:\n" + "\n".join(f"  - {u}" for u in tried)
+    raise RuntimeError(msg) from last_err

windtrader/cli.py

@@ -0,0 +1,148 @@
+"""
+windtrader CLI.
+
+Provides the `windtrader` command-line interface for driving the `windtrader-java`
+backend: `check` (parse-only validation), `echo`, and `export` (element JSON graph).
+
+Usage model
+-----------
+- The CLI reads SysML text from stdin.
+- It invokes the Java backend jar (`windtrader-java`) via the Python client.
+- It forwards stdout/stderr from the Java tool verbatim.
+- It exits with the same exit code as the Java tool.
+
+Subcommands
+-----------
+- `check` (default): parse-validate SysML text.
+- `echo`: print the normalized/echoed representation.
+- `export`: parse SysML and print the SysMLv2 element JSON graph (API shape).
+
+Exit codes (as defined by windtrader-java)
+------------------------------------------
+- 0: Valid SysML (parse succeeded)
+- 2: Invalid SysML (syntax/parse error)
+- 3: Runtime error (tool failure)
+- Any other non-zero: Unexpected failure
+
+Notes
+-----
+- `--version` prints the Python package version (not the Java backend version).
+- Use `--java-version` to select which `windtrader-java` release asset to download/use.
+- `--timeout` defaults per subcommand: 10s for `check`/`echo`, 120s for `export`
+  (export loads the standard library and runs resolve/transform).
+- An unknown subcommand is rejected by argparse with exit 2, the same code used
+  for invalid SysML. Prefer `check`/`echo`/`export` explicitly in scripts.
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+
+from . import __version__
+from ._jars import DEFAULT_VERSION
+from .client import echo as client_echo
+from .client import export as client_export
+from .client import validate
+
+_SUBCOMMAND_DEFAULT_TIMEOUT = {
+    "check": 10.0,
+    "echo": 10.0,
+    "export": 120.0,
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    """
+    Entry point for the `windtrader` CLI.
+
+    Parameters
+    ----------
+    argv:
+        Optional argument list (excluding program name). If None, arguments are read
+        from `sys.argv` (the default argparse behavior).
+
+    Returns
+    -------
+    int
+        The exit code returned by the Java backend process.
+
+    Behavior
+    --------
+    - Reads all input from stdin (blocking until EOF).
+    - Runs the selected subcommand with the provided Java backend version and timeout.
+    - Writes any backend stdout to stdout and stderr to stderr (verbatim).
+    - Returns the backend exit code (0/2/3), or 3 on a subprocess timeout.
+    """
+    p = argparse.ArgumentParser(
+        prog="windtrader",
+        description="SysML v2 wrapper around windtrader-java (check / echo / export)",
+    )
+
+    # Standard CLI version flag (prints Python package version)
+    p.add_argument(
+        "--version",
+        action="version",
+        version=f"windtrader {__version__}",
+    )
+
+    p.add_argument(
+        "subcommand",
+        nargs="?",
+        default="check",
+        choices=["check", "echo", "export"],
+        help="backend subcommand to run (default: check)",
+    )
+
+    # Java backend configuration
+    p.add_argument(
+        "--java-version",
+        default=DEFAULT_VERSION,
+        help="windtrader-java version to use (GitHub release asset version)",
+    )
+    p.add_argument(
+        "--timeout",
+        type=float,
+        default=None,
+        help="timeout in seconds for the Java subprocess "
+        "(default: 10s for check/echo, 120s for export)",
+    )
+
+    args = p.parse_args(argv)
+
+    timeout_s = (
+        args.timeout if args.timeout is not None else _SUBCOMMAND_DEFAULT_TIMEOUT[args.subcommand]
+    )
+
+    text = sys.stdin.read()
+
+    try:
+        if args.subcommand == "export":
+            res = client_export(text, version=args.java_version, timeout_s=timeout_s)
+        elif args.subcommand == "echo":
+            res = client_echo(text, version=args.java_version, timeout_s=timeout_s)
+        else:
+            res = validate(text, version=args.java_version, timeout_s=timeout_s)
+    except subprocess.TimeoutExpired:
+        # A timeout is a runtime/tool failure (exit 3), not a traceback.
+        sys.stderr.write("error: windtrader-java exceeded its timeout\n")
+        return 3
+
+    # Forward tool output verbatim
+    if res.stdout:
+        sys.stdout.write(res.stdout)
+        if not res.stdout.endswith("\n"):
+            sys.stdout.write("\n")
+
+    if res.stderr:
+        sys.stderr.write(res.stderr)
+        if not res.stderr.endswith("\n"):
+            sys.stderr.write("\n")
+
+    # Match Java tool exit codes
+    return int(res.exit_code)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

windtrader/client.py

@@ -0,0 +1,271 @@
+"""
+Python client for the `windtrader-java` CLI (check / echo / export).
+
+This module provides a small, stable API for driving the published
+`windtrader-java` shaded jar from Python. Each function runs the jar as an
+external black-box subprocess (`java -jar <jar> <subcommand>`) and captures
+its stdout/stderr/exit code; the jar is never imported or embedded.
+
+Subcommands and exit codes (as defined by windtrader-java)
+----------------------------------------------------------
+- `check`:  parse-only validation. 0 valid, 2 invalid, 3 runtime failure.
+- `echo`:   print a normalized/echoed representation when valid (implementation-defined).
+- `export`: parse SysML and print the SysMLv2 element JSON graph (API shape).
+
+The Python API mirrors these exactly: `validate`/`check`, `echo`, `export`.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from ._jars import DEFAULT_VERSION, get_jar_path
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    """
+    Result of invoking `windtrader-java` on a text input.
+
+    Attributes
+    ----------
+    ok:
+        True when the tool exited with code 0.
+    version:
+        windtrader-java version string used to resolve/download the jar.
+    exit_code:
+        Process exit code returned by the jar.
+    stdout:
+        Captured standard output from the jar.
+    stderr:
+        Captured standard error from the jar (often contains diagnostics).
+    jar_path:
+        Local filesystem path to the jar used during this invocation.
+    duration_s:
+        Wall-clock runtime in seconds for the subprocess call.
+    """
+
+    ok: bool
+    version: str
+    exit_code: int
+    stdout: str
+    stderr: str
+    jar_path: str
+    duration_s: float
+
+    @property
+    def is_invalid_syntax(self) -> bool:
+        """
+        True if the input is syntactically invalid per windtrader-java.
+
+        Convention: exit code 2 means "invalid SysML" (parse error).
+        """
+        return self.exit_code == 2
+
+    @property
+    def is_runtime_error(self) -> bool:
+        """
+        True if the tool failed for reasons other than a parse error.
+
+        Convention:
+        - 0 is success
+        - 2 is invalid syntax
+        Any other code indicates a tool/runtime failure (e.g., linkage errors).
+        """
+        return self.exit_code not in (0, 2)
+
+
+class WindtraderClient:
+    """
+    Thin client around `windtrader-java`.
+
+    This class is intentionally small. It:
+    - resolves/downloads the correct jar for a given version
+    - runs the jar with a bounded timeout
+    - returns captured stdout/stderr + metadata as a CommandResult
+    """
+
+    def __init__(self, version: str = DEFAULT_VERSION):
+        """
+        Parameters
+        ----------
+        version:
+            windtrader-java version string to download/use. Defaults to DEFAULT_VERSION.
+        """
+        self.version = version
+
+    def _run(self, subcommand: str, text: str, timeout_s: float) -> CommandResult:
+        """Run the jar with the given subcommand on `text`, returning a CommandResult."""
+        jar = get_jar_path(self.version)
+
+        t0 = time.time()
+        p = subprocess.run(
+            ["java", "-jar", str(jar), subcommand],
+            input=text,
+            text=True,
+            capture_output=True,
+            timeout=timeout_s,
+            check=False,
+        )
+        t1 = time.time()
+
+        return CommandResult(
+            ok=(p.returncode == 0),
+            version=self.version,
+            exit_code=p.returncode,
+            stdout=p.stdout or "",
+            stderr=p.stderr or "",
+            jar_path=str(jar),
+            duration_s=(t1 - t0),
+        )
+
+    def validate_text(self, text: str, timeout_s: float = 10.0) -> CommandResult:
+        """
+        Validate SysML v2 text using `windtrader-java check`.
+
+        Parameters
+        ----------
+        text:
+            SysML v2 textual syntax to validate.
+        timeout_s:
+            Subprocess timeout in seconds.
+
+        Returns
+        -------
+        CommandResult
+            Captures process exit code, stdout, stderr, jar path, and duration.
+        """
+        return self._run("check", text, timeout_s)
+
+    def echo(self, text: str, timeout_s: float = 10.0) -> CommandResult:
+        """
+        Run `windtrader-java echo` on SysML v2 text.
+
+        This is useful for debugging/parsing investigations because it returns the tool's
+        "echoed" / normalized representation (implementation-defined by windtrader-java).
+
+        Parameters
+        ----------
+        text:
+            SysML v2 textual syntax to parse/echo.
+        timeout_s:
+            Subprocess timeout in seconds.
+
+        Returns
+        -------
+        CommandResult
+            Captures process exit code, stdout, stderr, jar path, and duration.
+        """
+        return self._run("echo", text, timeout_s)
+
+    def export(self, text: str, timeout_s: float = 120.0) -> CommandResult:
+        """
+        Run `windtrader-java export` on SysML v2 text.
+
+        On success (exit 0) `stdout` holds the SysMLv2 element JSON graph (an
+        array of API-shaped elements). On invalid input (exit 2) no JSON is
+        emitted and `stderr` carries the parse diagnostics. On runtime failure
+        (exit 3, e.g. standard library unavailable) nothing valid is emitted.
+
+        Parameters
+        ----------
+        text:
+            SysML v2 textual syntax to export to its element JSON graph.
+        timeout_s:
+            Subprocess timeout in seconds (default higher than check/echo because
+            export loads the standard library and runs resolve/transform, which
+            can take ~55s on a cold JVM even for small models; 120s leaves headroom
+            for a loaded machine or cold CI runner).
+
+        Returns
+        -------
+        CommandResult
+            Captures process exit code, stdout (JSON), stderr, jar path, and duration.
+        """
+        return self._run("export", text, timeout_s)
+
+    def validate(self, text: str, timeout_s: float = 10.0) -> CommandResult:
+        """
+        Convenience alias for validate_text().
+
+        Kept for readability in user code and tests.
+        """
+        return self.validate_text(text, timeout_s=timeout_s)
+
+
+def validate(text: str, version: str = DEFAULT_VERSION, timeout_s: float = 10.0) -> CommandResult:
+    """
+    Validate SysML v2 text in one call without instantiating WindtraderClient.
+
+    Parameters
+    ----------
+    text:
+        SysML v2 textual syntax to validate.
+    version:
+        windtrader-java version string to download/use.
+    timeout_s:
+        Subprocess timeout in seconds.
+
+    Returns
+    -------
+    CommandResult
+        Captures exit code, stdout, stderr, jar path, and duration.
+    """
+    return WindtraderClient(version=version).validate_text(text, timeout_s=timeout_s)
+
+
+def echo(text: str, version: str = DEFAULT_VERSION, timeout_s: float = 10.0) -> CommandResult:
+    """
+    Echo SysML v2 text in one call without instantiating WindtraderClient.
+
+    Returns
+    -------
+    CommandResult
+        Captures exit code, stdout, stderr, jar path, and duration.
+    """
+    return WindtraderClient(version=version).echo(text, timeout_s=timeout_s)
+
+
+def export(text: str, version: str = DEFAULT_VERSION, timeout_s: float = 120.0) -> CommandResult:
+    """
+    Export SysML v2 text to its element JSON graph in one call.
+
+    On success (exit 0) `stdout` holds the SysMLv2 element JSON graph.
+
+    Returns
+    -------
+    CommandResult
+        Captures exit code, stdout (JSON), stderr, jar path, and duration.
+    """
+    return WindtraderClient(version=version).export(text, timeout_s=timeout_s)
+
+
+def validate_across_versions(
+    text: str,
+    versions: Sequence[str],
+    timeout_s: float = 10.0,
+) -> list[CommandResult]:
+    """
+    Validate the same SysML v2 text against multiple windtrader-java versions.
+
+    Parameters
+    ----------
+    text:
+        SysML v2 textual syntax to validate.
+    versions:
+        Iterable of windtrader-java version strings.
+    timeout_s:
+        Subprocess timeout for each version.
+
+    Returns
+    -------
+    list[CommandResult]
+        One result per version, in the same order as `versions`.
+    """
+    results: list[CommandResult] = []
+    for v in versions:
+        results.append(validate(text, version=v, timeout_s=timeout_s))
+    return results