tlaplus-cli 0.1.7__tar.gz

tlaplus_cli-0.1.7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Nikolskiy
+
+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.

tlaplus_cli-0.1.7/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+recursive-include tla/resources *.yaml
+include tla/py.typed

tlaplus_cli-0.1.7/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: tlaplus-cli
+Version: 0.1.7
+Summary: TLA+ tools: download TLC, compile custom modules, run model checker
+Author-email: Denis Nikolskiy <codeomatics@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nikolskiy/tlaplus-cli
+Project-URL: Repository, https://github.com/nikolskiy/tlaplus-cli
+Project-URL: Issues, https://github.com/nikolskiy/tlaplus-cli/issues
+Project-URL: Changelog, https://github.com/nikolskiy/tlaplus-cli/blob/main/CHANGELOG.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer<1.0.0,>=0.22.0
+Requires-Dist: requests<3.0.0,>=2.31.0
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: platformdirs<5.0,>=4.0
+Requires-Dist: pydantic<3.0.0,>=2.12.5
+Dynamic: license-file
+
+# TLA+ CLI
+
+Command-line tool for working with TLA+ specifications and the TLC model checker.
+
+## Installation
+
+Install system-wide via uv tool
+
+```bash
+uv tool install git+https://github.com/nikolskiy/tlaplus-cli
+```
+
+Upgrade:
+```bash
+uv tool upgrade tlaplus-cli
+```
+
+Uninstall
+
+```bash
+uv tool uninstall tlaplus-cli
+```
+
+## Usage
+
+### Download TLC
+
+```bash
+# Download stable release
+tla download
+
+# Download nightly build
+tla download --nightly
+```
+
+### Check Java Version
+
+```bash
+tla check-java
+```
+
+### Compile Custom Java Modules
+
+```bash
+tla build
+
+# Verbose output
+tla build --verbose
+```
+
+Compiles `.java` files from `workspace/modules/` into `workspace/classes/`.
+
+### Run TLC
+
+```bash
+tla tlc <spec_name>
+```
+
+For example:
+
+```bash
+tla tlc queue
+```
+
+## Configuration
+
+On first run, a default config is created at:
+
+```
+~/.config/tla/config.yaml
+```
+
+Edit this file to set your workspace path and TLC options:
+
+```yaml
+tla:
+  jar_name: tla2tools.jar
+  urls:
+    stable: https://github.com/tlaplus/tlaplus/releases/latest/download/tla2tools.jar
+    nightly: https://tla.msr-inria.inria.fr/tlatoolbox/ci/dist/tla2tools.jar
+
+workspace:
+  root: .                 # Project root (relative to CWD)
+  spec_dir: spec          # Directory containing .tla files
+  modules_dir: modules    # Directory containing .java files
+  classes_dir: classes    # Directory for compiled .class files
+
+tlc:
+  java_class: tlc2.TLC
+  overrides_class: tlc2.overrides.TLCOverrides
+
+java:
+  min_version: 11
+  opts:
+    - "-XX:+IgnoreUnrecognizedVMOptions"
+    - "-XX:+UseParallelGC"
+```
+
+### Directory Layout
+
+| Directory | Purpose | Location |
+|---|---|---|
+| Config | `config.yaml` | `~/.config/tla/` |
+| Cache | `tla2tools.jar` | `~/.cache/tla/` |
+| Workspace | specs + modules + classes | Set via `workspace.root` in config |
+
+## Note on Package Name
+
+This package is distributed on PyPI as **`tlaplus-cli`** but imports as **`tla`**. There is a separate, unrelated [`tla`](https://pypi.org/project/tla/) package on PyPI (a TLA+ parser). If you have both installed, they will conflict. In practice this is unlikely since they serve different purposes, but be aware of it.
+
+## Dependencies
+
+*   **Java >= 11**: Required for TLC.
+*   [**uv**](https://docs.astral.sh/uv/getting-started/installation/): For installing the tool.

tlaplus_cli-0.1.7/README.md

@@ -0,0 +1,114 @@
+# TLA+ CLI
+
+Command-line tool for working with TLA+ specifications and the TLC model checker.
+
+## Installation
+
+Install system-wide via uv tool
+
+```bash
+uv tool install git+https://github.com/nikolskiy/tlaplus-cli
+```
+
+Upgrade:
+```bash
+uv tool upgrade tlaplus-cli
+```
+
+Uninstall
+
+```bash
+uv tool uninstall tlaplus-cli
+```
+
+## Usage
+
+### Download TLC
+
+```bash
+# Download stable release
+tla download
+
+# Download nightly build
+tla download --nightly
+```
+
+### Check Java Version
+
+```bash
+tla check-java
+```
+
+### Compile Custom Java Modules
+
+```bash
+tla build
+
+# Verbose output
+tla build --verbose
+```
+
+Compiles `.java` files from `workspace/modules/` into `workspace/classes/`.
+
+### Run TLC
+
+```bash
+tla tlc <spec_name>
+```
+
+For example:
+
+```bash
+tla tlc queue
+```
+
+## Configuration
+
+On first run, a default config is created at:
+
+```
+~/.config/tla/config.yaml
+```
+
+Edit this file to set your workspace path and TLC options:
+
+```yaml
+tla:
+  jar_name: tla2tools.jar
+  urls:
+    stable: https://github.com/tlaplus/tlaplus/releases/latest/download/tla2tools.jar
+    nightly: https://tla.msr-inria.inria.fr/tlatoolbox/ci/dist/tla2tools.jar
+
+workspace:
+  root: .                 # Project root (relative to CWD)
+  spec_dir: spec          # Directory containing .tla files
+  modules_dir: modules    # Directory containing .java files
+  classes_dir: classes    # Directory for compiled .class files
+
+tlc:
+  java_class: tlc2.TLC
+  overrides_class: tlc2.overrides.TLCOverrides
+
+java:
+  min_version: 11
+  opts:
+    - "-XX:+IgnoreUnrecognizedVMOptions"
+    - "-XX:+UseParallelGC"
+```
+
+### Directory Layout
+
+| Directory | Purpose | Location |
+|---|---|---|
+| Config | `config.yaml` | `~/.config/tla/` |
+| Cache | `tla2tools.jar` | `~/.cache/tla/` |
+| Workspace | specs + modules + classes | Set via `workspace.root` in config |
+
+## Note on Package Name
+
+This package is distributed on PyPI as **`tlaplus-cli`** but imports as **`tla`**. There is a separate, unrelated [`tla`](https://pypi.org/project/tla/) package on PyPI (a TLA+ parser). If you have both installed, they will conflict. In practice this is unlikely since they serve different purposes, but be aware of it.
+
+## Dependencies
+
+*   **Java >= 11**: Required for TLC.
+*   [**uv**](https://docs.astral.sh/uv/getting-started/installation/): For installing the tool.

tlaplus_cli-0.1.7/pyproject.toml

@@ -0,0 +1,137 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tlaplus-cli"
+version = "0.1.7"
+description = "TLA+ tools: download TLC, compile custom modules, run model checker"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.22.0,<1.0.0",
+    "requests>=2.31.0,<3.0.0",
+    "pyyaml>=6.0,<7.0",
+    "platformdirs>=4.0,<5.0",
+    "pydantic>=2.12.5,<3.0.0",
+]
+authors = [
+    {name = "Denis Nikolskiy", email = "codeomatics@gmail.com"}
+]
+license = "MIT"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/nikolskiy/tlaplus-cli"
+Repository = "https://github.com/nikolskiy/tlaplus-cli"
+Issues = "https://github.com/nikolskiy/tlaplus-cli/issues"
+Changelog = "https://github.com/nikolskiy/tlaplus-cli/blob/main/CHANGELOG.md"
+
+[project.scripts]
+tla = "tla.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["tla*"]
+
+[tool.setuptools.package-data]
+tla = ["resources/default_config.yaml", "py.typed"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2,<10.0.0",
+    "pytest-cov>=7.0.0,<8.0.0",
+    "pytest-mock>=3.15.1,<4.0.0",
+    "ruff>=0.9.0,<1.0.0",
+    "mypy>=1.0.0,<2.0.0",
+    "types-PyYAML>=6.0.12.12,<7.0.0.0",
+    "types-requests>=2.31.0.2,<3.0.0.0",
+    "poethepoet>=0.24.0,<1.0.0",
+    "detect-secrets>=1.5.0,<2.0.0",
+    "pre-commit>=3.5.0,<4.0.0",
+    "pre-commit-hooks>=6.0.0,<7.0.0",
+    "twine>=6.0.0,<7.0.0",
+]
+
+[tool.pytest.ini_options]
+addopts = "--cov=tla --cov-report=term-missing"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "F",      # Pyflakes: logic errors
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "I",      # isort: import sorting
+    "N",      # pep8-naming: naming conventions
+    "UP",     # pyupgrade: upgrade syntax for newer python versions
+    "PL",     # Pylint: various checks (convention, refactor, warning, etc.)
+    "B",      # flake8-bugbear: finds likely bugs and design problems
+    "SIM",    # flake8-simplify: suggests simpler python constructs
+    "C4",     # flake8-comprehensions: better list/set/dict comprehensions
+    "PIE",    # flake8-pie: miscellaneous lints
+    "TCH",    # flake8-type-checking: move imports to type-checking blocks
+    "PGH",    # pygrep-hooks: regex based checks
+    "G",      # flake8-logging-format: validate logging format strings
+    "RUF",    # Ruff-specific rules
+    "PTH",    # flake8-use-pathlib: replace os.path with pathlib
+    "ARG",    # flake8-unused-arguments: find unused function arguments
+    "RET",    # flake8-return: cleaner return logic
+    "TRY",    # tryceratops: prevent exception handling anti-patterns
+]
+ignore = [
+    "PLR2004", # Magic value used in comparison
+    "PLW1510", # subprocess.run without explicit check
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "ARG001", # Unused arguments are common in tests (fixtures)
+]
+
+[tool.poe.tasks]
+check = "pre-commit run --all-files"
+lint = ["lint-ruff", "type-check"]
+lint-ruff = "ruff check ."
+type-check = "mypy ."
+fix = ["format", "lint-fix"]
+format = "ruff format ."
+lint-fix = "ruff check --fix ."
+test = "pytest"
+install-hooks = "pre-commit install --install-hooks"
+audit = "detect-secrets audit .secrets.baseline"
+build = "uv build"
+clean = "rm -rf dist"
+
+twine-check = "twine check dist/*.whl dist/*.tar.gz"
+
+[tool.poe.tasks.check-release]
+sequence = [
+    "check",
+    "clean",
+    "build",
+    "twine-check",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = false
+exclude = ["build", "tests/"]
+
+# Per-module overrides for libraries without strict types
+[[tool.mypy.overrides]]
+module = "platformdirs.*"
+ignore_missing_imports = true

tlaplus_cli-0.1.7/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tlaplus_cli-0.1.7/tests/test_build_tlc_module.py

@@ -0,0 +1,81 @@
+import shutil
+
+import pytest
+
+from tla import build_tlc_module
+
+# Define paths relative to the test file
+# Check if javac is available
+JAVAC_AVAILABLE = shutil.which("javac") is not None
+
+
+@pytest.mark.skipif(not JAVAC_AVAILABLE, reason="javac not found")
+def test_build_integration(mocker, tmp_path, queue_dir, base_settings):
+    """
+    Integration test for build_tlc_module.build().
+    Uses the actual files in tla-example and the real tla2tools.jar (if available).
+    Verified output classes are generated in a temporary directory.
+    """
+    # Create a temporary classes directory
+    classes_dir = tmp_path / "classes"
+
+    # Configure base_settings for this test
+    base_settings.workspace.root = queue_dir
+    base_settings.workspace.classes_dir = classes_dir
+
+    # Patch load_config to return our mock config
+    mocker.patch("tla.build_tlc_module.load_config", return_value=base_settings)
+
+    # Patch workspace_root to return the example directory
+    mocker.patch("tla.build_tlc_module.workspace_root", return_value=queue_dir)
+
+    # Run build
+    # We catch typer.Exit just in case, though it shouldn't be raised on success
+    try:
+        build_tlc_module.build(verbose=True)
+    except SystemExit as e:
+        # build() raises typer.Exit(1) on failure
+        # If it raises, we fail the test
+        assert e.code == 0, "Build failed with SystemExit"
+
+    # Verify outputs
+    assert classes_dir.exists(), "Classes directory not created"
+
+    # Verify TLCOverrides.class exists
+    # The source is modules/tlc2/overrides/TLCOverrides.java
+    # Package is tlc2.overrides, so output should be in tlc2/overrides/
+    output_class = classes_dir / "tlc2/overrides/TLCOverrides.class"
+    assert output_class.exists(), f"Class file not found at {output_class}"
+
+    # Verify META-INF service file
+    service_file = classes_dir / "META-INF/services/tlc2.overrides.ITLCOverrides"
+    assert service_file.exists(), "Service file not found"
+
+    content = service_file.read_text().strip()
+    assert content == "tlc2.overrides.TLCOverrides", f"Unexpected service file content: {content}"
+
+
+@pytest.mark.skipif(not JAVAC_AVAILABLE, reason="javac not found")
+def test_build_custom_overrides(mocker, tmp_path, queue_dir, base_settings):
+    """
+    Test build with custom overrides class configuration.
+    """
+    classes_dir = tmp_path / "classes"
+
+    # Configure custom override
+    custom_override = "com.example.MyOverrides"
+    base_settings.tlc.overrides_class = custom_override
+    base_settings.workspace.root = queue_dir
+    base_settings.workspace.classes_dir = classes_dir
+
+    mocker.patch("tla.build_tlc_module.load_config", return_value=base_settings)
+    mocker.patch("tla.build_tlc_module.workspace_root", return_value=queue_dir)
+
+    try:
+        build_tlc_module.build(verbose=False)
+    except SystemExit as e:
+        assert e.code == 0
+
+    service_file = classes_dir / "META-INF/services/tlc2.overrides.ITLCOverrides"
+    assert service_file.exists()
+    assert service_file.read_text().strip() == custom_override

tlaplus_cli-0.1.7/tests/test_check_java.py

@@ -0,0 +1,59 @@
+from unittest.mock import MagicMock
+
+import pytest
+import typer
+
+from tla import check_java
+
+
+def test_parse_java_version():
+    """Test parsing of Java version strings."""
+    assert check_java.parse_java_version("1.8.0_202") == 8
+    assert check_java.parse_java_version("9.0.4") == 9
+    assert check_java.parse_java_version("11.0.2") == 11
+    assert check_java.parse_java_version("17") == 17
+    assert check_java.parse_java_version("21.0.1") == 21
+
+
+def test_get_java_version_success(mocker):
+    """Test successful retrieval of Java version."""
+    mock_run = mocker.patch("subprocess.run")
+    # Simulate java -version output (it usually goes to stderr)
+    mock_run.return_value = MagicMock(
+        stdout="", stderr='openjdk version "11.0.2" 2019-01-15\nOpenJDK Runtime Environment 18.9...'
+    )
+    mocker.patch("shutil.which", return_value="/usr/bin/java")
+
+    assert check_java.get_java_version() == "11.0.2"
+
+
+def test_get_java_version_not_found(mocker):
+    """Test when java is not found in PATH."""
+    mocker.patch("shutil.which", return_value=None)
+    assert check_java.get_java_version() is None
+
+
+def test_check_java_version_ok(mocker):
+    """Test check passes when version is sufficient."""
+    mocker.patch("tla.check_java.get_java_version", return_value="11.0.2")
+    # Should not raise
+    check_java.check_java_version(11)
+    check_java.check_java_version(8)
+
+
+def test_check_java_version_too_low(mocker):
+    """Test check fails when version is too low."""
+    mocker.patch("tla.check_java.get_java_version", return_value="1.8.0_202")
+
+    with pytest.raises(typer.Exit) as e:
+        check_java.check_java_version(11)
+    assert e.value.exit_code == 1
+
+
+def test_check_java_version_missing(mocker):
+    """Test check fails when java is missing."""
+    mocker.patch("tla.check_java.get_java_version", return_value=None)
+
+    with pytest.raises(typer.Exit) as e:
+        check_java.check_java_version(11)
+    assert e.value.exit_code == 1

tlaplus_cli-0.1.7/tests/test_cli.py

@@ -0,0 +1,43 @@
+
+import pytest
+import typer
+from typer.testing import CliRunner
+
+from tla.cli import app, version_callback
+
+runner = CliRunner()
+
+
+def test_version_callback_exits(mocker):
+    """Test version callback exits after printing."""
+    mock_metadata = mocker.patch("importlib.metadata.metadata")
+    mock_metadata.return_value = {
+        "Name": "tlaplus-cli",
+        "Version": "1.2.3",
+        "Summary": "Test summary",
+    }
+
+    with pytest.raises(typer.Exit):
+        version_callback(True)
+
+    mock_metadata.assert_called_once_with("tlaplus-cli")
+
+
+def test_cli_version_flag(mocker):
+    """Test 'tla --version' command."""
+    mock_metadata = mocker.patch("importlib.metadata.metadata")
+    mock_metadata.return_value = {
+        "Name": "tlaplus-cli",
+        "Version": "1.2.3",
+        "Summary": "Test summary",
+    }
+
+    # Running the CLI with --version
+    result = runner.invoke(app, ["--version"])
+
+    # It should exit with 0
+    assert result.exit_code == 0
+    assert "tlaplus-cli v1.2.3" in result.stdout
+    assert "Test summary" in result.stdout
+
+    mock_metadata.assert_called_once_with("tlaplus-cli")