tlaplus-cli 0.6.0__tar.gz → 0.8.1__tar.gz

tlaplus_cli-0.8.1/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: tlaplus-cli
+Version: 0.8.1
+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
+Requires-Dist: truststore<1.0.0,>=0.9.0
+Requires-Dist: rich<14.0.0,>=13.7.0
+Dynamic: license-file
+
+# TLA+ CLI
+
+Command-line tool for working with TLA+ specifications and the TLC model checker.
+
+## Project Goals
+
+1. Simplify managing TLA+ tools such as TLC, community modules, custom modules, etc.
+2. Run TLA tools in a single CLI interface.
+3. Manage and display the tool outputs.
+
+## Quick Start & Usage
+
+### 1. Toolset Management (`tla tools`)
+* `tla check-java`: Verify Java installation and compatibility.
+* `tla tools list`: List available and installed toolset versions (`tla2tools.jar`).
+* `tla tools install [vX.Y.Z]`: Download and install a toolset version.
+* `tla tools pin <version>`: Set default toolset version for TLC runs.
+
+### 2. Model Checking (`tla tlc`)
+* `tla tlc <spec>`: Execute TLC model checker on a specification.
+* `tla tlc <spec> --show-command`: Inspect exact JVM command before execution.
+
+### 3. Custom Java Modules (`tla modules`)
+* `tla modules add <path>`: Compile Java operator overrides and register module in CLI cache.
+* `tla modules list`: Display cached custom modules.
+* `tla modules remove <name>`: Remove custom module from cache.
+
+For complete, runnable specifications and Java module examples, see [docs/examples](docs/examples/).
+
+## Quick Installation
+
+### Via `uv tool`
+```bash
+uv tool install tlaplus-cli
+```
+
+### Via Nix Flakes
+```bash
+nix profile install github:nikolskiy/tlaplus-cli
+```

tlaplus_cli-0.8.1/README.md

@@ -0,0 +1,40 @@
+# TLA+ CLI
+
+Command-line tool for working with TLA+ specifications and the TLC model checker.
+
+## Project Goals
+
+1. Simplify managing TLA+ tools such as TLC, community modules, custom modules, etc.
+2. Run TLA tools in a single CLI interface.
+3. Manage and display the tool outputs.
+
+## Quick Start & Usage
+
+### 1. Toolset Management (`tla tools`)
+* `tla check-java`: Verify Java installation and compatibility.
+* `tla tools list`: List available and installed toolset versions (`tla2tools.jar`).
+* `tla tools install [vX.Y.Z]`: Download and install a toolset version.
+* `tla tools pin <version>`: Set default toolset version for TLC runs.
+
+### 2. Model Checking (`tla tlc`)
+* `tla tlc <spec>`: Execute TLC model checker on a specification.
+* `tla tlc <spec> --show-command`: Inspect exact JVM command before execution.
+
+### 3. Custom Java Modules (`tla modules`)
+* `tla modules add <path>`: Compile Java operator overrides and register module in CLI cache.
+* `tla modules list`: Display cached custom modules.
+* `tla modules remove <name>`: Remove custom module from cache.
+
+For complete, runnable specifications and Java module examples, see [docs/examples](docs/examples/).
+
+## Quick Installation
+
+### Via `uv tool`
+```bash
+uv tool install tlaplus-cli
+```
+
+### Via Nix Flakes
+```bash
+nix profile install github:nikolskiy/tlaplus-cli
+```

{tlaplus_cli-0.6.0 → tlaplus_cli-0.8.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tlaplus-cli"
-version = "0.6.0"
+version = "0.8.1"
 description = "TLA+ tools: download TLC, compile custom modules, run model checker"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -68,7 +68,7 @@ dev = [
 
 [tool.pytest.ini_options]
 addopts = "--cov=tlaplus_cli --cov-report=term-missing"
-testpaths = ["tests"]
+testpaths = ["tests/unit"]
 
 [tool.ruff]
 line-length = 120

{tlaplus_cli-0.6.0 → tlaplus_cli-0.8.1}/src/tlaplus_cli/cli.py

@@ -11,6 +11,7 @@ from tlaplus_cli.cmd.modules import app as modules_app
 from tlaplus_cli.cmd.tlc import tlc as run_tlc_cmd
 from tlaplus_cli.cmd.tools import app as tools_app
 from tlaplus_cli.config.loader import load_config
+from tlaplus_cli.versioning import get_app_version
 
 app = typer.Typer(
     name="tla",
@@ -23,7 +24,8 @@ app = typer.Typer(
 def version_callback(value: bool) -> None:
     if value:
         meta = importlib.metadata.metadata("tlaplus-cli")
-        typer.echo(f"{meta['Name']} v{meta['Version']}")
+        app_ver = get_app_version(base_version=meta["Version"])
+        typer.echo(f"{meta['Name']} v{app_ver}")
         typer.echo(meta["Summary"])
         raise typer.Exit()
 

tlaplus_cli-0.8.1/src/tlaplus_cli/cmd/modules/__init__.py

@@ -0,0 +1,16 @@
+import typer
+
+app = typer.Typer(name="modules", help="Manage TLA+ Java modules.", no_args_is_help=True)
+
+
+# Import functions for new commands
+from .add import add_module  # noqa: E402
+from .list import list_modules  # noqa: E402
+from .path import show_modules_path  # noqa: E402
+from .remove import remove_module  # noqa: E402
+
+# Register new commands with the typer app
+app.command(name="add")(add_module)
+app.command(name="list")(list_modules)
+app.command(name="remove")(remove_module)
+app.command(name="path")(show_modules_path)

tlaplus_cli-0.8.1/src/tlaplus_cli/cmd/modules/add.py

@@ -0,0 +1,140 @@
+import datetime
+import json
+import os
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+import typer
+
+from tlaplus_cli.config.loader import load_config
+from tlaplus_cli.java.classpath import ClasspathResolver, ResolveMode
+from tlaplus_cli.tlc.compiler import get_tlc_jar_path
+from tlaplus_cli.tlc.run_cache import clear_tlc_run_cache
+from tlaplus_cli.versioning.paths import get_modules_dir
+
+
+def find_override_classes(java_files: list[Path]) -> list[str]:
+    """Find all class names implementing ITLCOverrides in Java files."""
+    override_classes = []
+    package_pattern = re.compile(r"package\s+([a-zA-Z0-9_.]+)\s*;")
+    class_pattern = re.compile(
+        r"\bclass\s+([a-zA-Z0-9_]+)\b[^{]*\bimplements\b[^{]*\b(tlc2\.overrides\.)?ITLCOverrides\b"
+    )
+
+    for jf in java_files:
+        try:
+            content = jf.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+
+        # Strip comments to prevent false matches
+        content_no_comments = re.sub(r"//.*", "", content)
+        content_no_comments = re.sub(r"/\*.*?\*/", "", content_no_comments, flags=re.DOTALL)
+
+        package_match = package_pattern.search(content_no_comments)
+        package_name = package_match.group(1) if package_match else ""
+
+        for match in class_pattern.finditer(content_no_comments):
+            class_name = match.group(1)
+            full_class_name = f"{package_name}.{class_name}" if package_name else class_name
+            override_classes.append(full_class_name)
+
+    return override_classes
+
+
+def add_module(  # noqa: PLR0912, PLR0915
+    path: str = typer.Argument(..., help="Path to the module directory to add."),
+) -> None:
+    """Compile custom Java overrides and add/update the module in the cache."""
+    source_dir = Path(path).resolve()
+    if not source_dir.is_dir():
+        typer.echo(f"Error: Path does not exist or is not a directory: {source_dir}", err=True)
+        raise typer.Exit(1)
+
+    config = load_config()
+    module_name = source_dir.name
+    target_dir = get_modules_dir() / module_name
+
+    # Overwrite if exists
+    if target_dir.exists():
+        shutil.rmtree(target_dir)
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # 1. Copy directories (lib, modules, tlc2, and test/tests)
+    def copy_subfolder(subname: str) -> None:
+        src = source_dir / subname
+        if src.is_dir():
+            shutil.copytree(src, target_dir / subname)
+
+    typer.echo("Copying subfolders (lib, modules, test, tlc2)...")
+    copy_subfolder("lib")
+    copy_subfolder("modules")
+    copy_subfolder("tlc2")
+
+    if (source_dir / "test").is_dir():
+        copy_subfolder("test")
+    elif (source_dir / "tests").is_dir():
+        copy_subfolder("tests")
+
+    # 2. Compile Java overrides in cached version if tlc2/overrides exists
+    java_files = []
+    for candidate in [target_dir / "modules" / "tlc2" / "overrides", target_dir / "tlc2" / "overrides"]:
+        if candidate.is_dir():
+            java_files.extend(list(candidate.rglob("*.java")))
+
+    if java_files:
+        # Build classpath including tool_jar and local libs from the cached folder
+        cached_lib = target_dir / "lib"
+        extra_libs = []
+        if cached_lib.is_dir():
+            extra_libs.extend([str(j.absolute()) for j in cached_lib.glob("*.jar")])
+
+        tool_jar = get_tlc_jar_path()
+        if not tool_jar.exists():
+            typer.echo("Error: tla2tools.jar not found. Run 'tla tools install' first.", err=True)
+            shutil.rmtree(target_dir, ignore_errors=True)
+            raise typer.Exit(1)
+
+        resolver = ClasspathResolver(config, project_root=None, tool_jar=tool_jar, extra_libs=extra_libs)
+        classpath = os.pathsep.join(resolver.resolve(ResolveMode.COMPILE))
+
+        classes_dir = target_dir / "classes"
+        classes_dir.mkdir(parents=True, exist_ok=True)
+
+        cmd = ["javac", "-cp", classpath, "-d", str(classes_dir), *[str(f) for f in java_files]]
+        typer.echo("Compiling Java files in cached tlc2/overrides...")
+        try:
+            subprocess.run(cmd, check=True, capture_output=True, text=True)
+        except FileNotFoundError as err:
+            typer.echo("Error: 'javac' not found. Ensure JDK is installed.", err=True)
+            shutil.rmtree(target_dir, ignore_errors=True)
+            raise typer.Exit(1) from err
+        except subprocess.CalledProcessError as err:
+            typer.echo("Compilation failed!", err=True)
+            typer.echo(err.stdout, err=True)
+            typer.echo(err.stderr, err=True)
+            shutil.rmtree(target_dir, ignore_errors=True)
+            raise typer.Exit(1) from err
+
+        # Write service file
+        meta_inf = classes_dir / "META-INF" / "services"
+        meta_inf.mkdir(parents=True, exist_ok=True)
+        service_file = meta_inf / "tlc2.overrides.ITLCOverrides"
+
+        override_classes = find_override_classes(java_files)
+        if not override_classes:
+            override_classes = [config.tlc.overrides_class]
+
+        with service_file.open("w") as f:
+            for cls in override_classes:
+                f.write(f"{cls}\n")
+
+    # 3. Create metadata.json
+    metadata = {"name": module_name, "built_at": datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
+    with (target_dir / "metadata.json").open("w") as f:
+        json.dump(metadata, f, indent=2)
+
+    clear_tlc_run_cache()
+    typer.echo(f"Module '{module_name}' successfully added to cache.")

tlaplus_cli-0.8.1/src/tlaplus_cli/cmd/modules/list.py

@@ -0,0 +1,45 @@
+import json
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from tlaplus_cli.versioning.paths import get_modules_dir
+
+
+def list_modules() -> None:
+    """List all custom TLA+ modules added to the cache."""
+    modules_dir = get_modules_dir()
+
+    if not modules_dir.is_dir():
+        typer.echo("No modules currently added.")
+        return
+
+    modules_data = []
+    for item in sorted(modules_dir.iterdir()):
+        if item.is_dir():
+            metadata_file = item / "metadata.json"
+            if metadata_file.exists():
+                try:
+                    meta = json.loads(metadata_file.read_text())
+                    name = meta.get("name", item.name)
+                    built_at = meta.get("built_at", "Unknown")
+                    modules_data.append((name, built_at))
+                except Exception:
+                    modules_data.append((item.name, "Corrupt Metadata"))
+            else:
+                modules_data.append((item.name, "Unknown"))
+
+    if not modules_data:
+        typer.echo("No modules currently added.")
+        return
+
+    table = Table()
+    table.add_column("Module Name", style="cyan")
+    table.add_column("Last Built/Modified", style="magenta")
+
+    for name, built_at in modules_data:
+        table.add_row(name, built_at)
+
+    console = Console()
+    console.print(table)

tlaplus_cli-0.8.1/src/tlaplus_cli/cmd/modules/path.py

@@ -0,0 +1,68 @@
+import os
+from pathlib import Path
+
+import typer
+
+from tlaplus_cli.config.loader import load_config
+from tlaplus_cli.java.classpath import ClasspathResolver, ResolveMode, SubdirType
+from tlaplus_cli.tlc.compiler import get_tlc_jar_path
+from tlaplus_cli.versioning.paths import get_modules_dir
+
+
+def show_modules_path() -> None:  # noqa: PLR0912
+    """Display the active paths that will be included when running TLC."""
+    config_obj = load_config()
+    tool_jar = get_tlc_jar_path()
+
+    resolver = ClasspathResolver(config_obj, project_root=None, tool_jar=tool_jar)
+
+    # 1. Source Paths (-DTLA-Library)
+    tla_library = resolver.get_tla_library_property()
+    typer.echo("Source Paths (-DTLA-Library):")
+    if tla_library:
+        for p in tla_library.split(os.pathsep):
+            typer.echo(f"  - {p}")
+    else:
+        typer.echo("  None")
+
+    # 2. Classes Paths
+    classes_paths = []
+    project_classes = resolver.get_project_path(SubdirType.CLASSES)
+    if project_classes:
+        classes_paths.append(str(project_classes.absolute()))
+
+    managed_dir = get_modules_dir()
+    if managed_dir.is_dir():
+        for item in sorted(managed_dir.iterdir()):
+            if item.is_dir():
+                mod_classes = item / "classes"
+                if mod_classes.is_dir():
+                    classes_paths.append(str(mod_classes.absolute()))
+
+    typer.echo("\nClasses Paths:")
+    if classes_paths:
+        for p in classes_paths:
+            typer.echo(f"  - {p}")
+    else:
+        typer.echo("  None")
+
+    # 3. Library Paths (JARs)
+    libs = resolver.resolve(ResolveMode.RUNTIME)
+    tool_jar_abs = str(tool_jar.absolute()) if tool_jar.exists() else ""
+
+    # Filter out classes directories and tool_jar to show only external library JARs
+    only_libs = []
+    for p in libs:
+        if p == tool_jar_abs:
+            continue
+        p_path = Path(p)
+        if p_path.name == "classes" and p_path.is_dir():
+            continue
+        only_libs.append(p)
+
+    typer.echo("\nLibrary Paths (JARs):")
+    if only_libs:
+        for p in only_libs:
+            typer.echo(f"  - {p}")
+    else:
+        typer.echo("  None")

tlaplus_cli-0.8.1/src/tlaplus_cli/cmd/modules/remove.py

@@ -0,0 +1,22 @@
+import shutil
+
+import typer
+
+from tlaplus_cli.tlc.run_cache import clear_tlc_run_cache
+from tlaplus_cli.versioning.paths import get_modules_dir
+
+
+def remove_module(module_name: str = typer.Argument(..., help="Name of the module to remove from cache.")) -> None:
+    """Remove a custom module from the cache."""
+    target_dir = get_modules_dir() / module_name
+    if not target_dir.is_dir():
+        typer.echo(f"Error: Module '{module_name}' not found in cache.", err=True)
+        raise typer.Exit(1)
+
+    try:
+        shutil.rmtree(target_dir)
+        clear_tlc_run_cache()
+        typer.echo(f"Module '{module_name}' successfully deleted from cache.")
+    except OSError as e:
+        typer.echo(f"Error: Failed to delete module: {e}", err=True)
+        raise typer.Exit(1) from e