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

tlaplus_cli-0.7.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: tlaplus-cli
+Version: 0.7.0
+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 tools outputs.
+
+## Features
+
+* [Managing TLA+ Tools](docs/managing-tlaplus-tools/managing-tla2tools.md): Verify Java requirements, manage/pin `tla2tools.jar` versions, and handle cache settings.
+* [Running TLC](docs/tlc/tlc.md): Run the TLC model checker, inspect commands, and execute model checking with custom modules.
+* [Custom Java Modules](docs/java-modules-for-tlc/README.md): Compile, register, and manage custom Java operator overrides for TLC using automated CLI commands.
+
+## Installation
+
+For detailed installation instructions, please refer to:
+* [Installation via uv tool](docs/installation/uv-tool.md)
+* [Nix Flakes Installation & Development](docs/installation/nix.md)

tlaplus_cli-0.7.0/README.md

@@ -0,0 +1,21 @@
+# 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 tools outputs.
+
+## Features
+
+* [Managing TLA+ Tools](docs/managing-tlaplus-tools/managing-tla2tools.md): Verify Java requirements, manage/pin `tla2tools.jar` versions, and handle cache settings.
+* [Running TLC](docs/tlc/tlc.md): Run the TLC model checker, inspect commands, and execute model checking with custom modules.
+* [Custom Java Modules](docs/java-modules-for-tlc/README.md): Compile, register, and manage custom Java operator overrides for TLC using automated CLI commands.
+
+## Installation
+
+For detailed installation instructions, please refer to:
+* [Installation via uv tool](docs/installation/uv-tool.md)
+* [Nix Flakes Installation & Development](docs/installation/nix.md)

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tlaplus-cli"
-version = "0.6.0"
+version = "0.7.0"
 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.7.0/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.7.0/src/tlaplus_cli/cmd/modules/add.py

@@ -0,0 +1,138 @@
+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.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)
+
+    typer.echo(f"Module '{module_name}' successfully added to cache.")

tlaplus_cli-0.7.0/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.7.0/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.7.0/src/tlaplus_cli/cmd/modules/remove.py

@@ -0,0 +1,20 @@
+import shutil
+
+import typer
+
+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)
+        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

{tlaplus_cli-0.6.0 → tlaplus_cli-0.7.0}/src/tlaplus_cli/cmd/tlc.py

@@ -1,3 +1,5 @@
+import sys
+
 import typer
 from rich.console import Console
 from rich.live import Live
@@ -7,6 +9,7 @@ from tlaplus_cli.config.loader import load_config
 from tlaplus_cli.java.classpath import ClasspathResolver
 from tlaplus_cli.project import find_project_root
 from tlaplus_cli.tlc.compiler import get_tlc_jar_path
+from tlaplus_cli.tlc.components import StatsTableFormatter, StatusFooterRenderable
 from tlaplus_cli.tlc.formatter import TlcFormatter
 from tlaplus_cli.tlc.models import CheckState, ModelCheckResult
 from tlaplus_cli.tlc.runner import (
@@ -78,6 +81,7 @@ def tlc(  # noqa: PLR0912, PLR0915
         help="Refresh interval for the output (seconds).",
     ),
     coverage: bool = typer.Option(False, "--coverage", help="Enable code coverage visualization."),
+    raw: bool = typer.Option(False, "--raw", help="Run TLC in raw mode without structured tool mode formatting."),
 ) -> None:
     """Run TLC model checker on a TLA+ specification."""
     # version argument is handled by version_callback (is_eager=True)
@@ -96,16 +100,80 @@ def tlc(  # noqa: PLR0912, PLR0915
         typer.echo(" ".join(cmd))
         raise typer.Exit(0)
 
+    if raw:
+        exit_code = run_tlc(spec, coverage=coverage, raw=True)
+        raise typer.Exit(exit_code)
+
     tlc_version = get_tlc_version() or "unknown"
     formatter = TlcFormatter(tlc_version=tlc_version)
     layout = formatter.create_layout()
 
+    is_tty = sys.stdout.isatty()
+
     try:
         final_result: list[ModelCheckResult] = []
+        printed_logs_count = 0
+        printed_stats_count = 0
+        stats_header_printed = False
+        stats_border_printed = False
+
+        if is_tty:
+            table_formatter = StatsTableFormatter()
+            footer_renderable = StatusFooterRenderable(ModelCheckResult())
+            console = Console()
+
+            with Live(footer_renderable, refresh_per_second=4, screen=False) as live:
+
+                def wrapped_callback(res: ModelCheckResult) -> None:
+                    nonlocal printed_logs_count, printed_stats_count, stats_header_printed, stats_border_printed
+
+                    # Keep tests happy by updating the formatter
+                    formatter.update(layout, res)
+
+                    if not final_result:
+                        final_result.append(res)
+                    else:
+                        final_result[0] = res
+
+                    # Update the live status footer dynamic data
+                    footer_renderable.result = res
 
-        with Live(layout, refresh_per_second=4, screen=False):
+                    # Stream any new logs
+                    if len(res.output_lines) > printed_logs_count:
+                        new_logs = res.output_lines[printed_logs_count:]
+                        for log in new_logs:
+                            live.console.print(log.strip())
+                        printed_logs_count = len(res.output_lines)
+
+                    # Stream any new progress stats
+                    if len(res.initial_states_stat) > printed_stats_count:
+                        new_stats = res.initial_states_stat[printed_stats_count:]
+                        for stat in new_stats:
+                            if not stats_header_printed:
+                                live.console.print("\nState Space Progress:\n")
+                                live.console.print(table_formatter.get_header())
+                                live.console.print(table_formatter.get_border())
+                                stats_header_printed = True
+
+                            row_str = table_formatter.format_row(stat)
+                            live.console.print(row_str)
+                        printed_stats_count = len(res.initial_states_stat)
+
+                    # Print bottom border when execution changes state to non-running
+                    if res.state != CheckState.Running and stats_header_printed and not stats_border_printed:
+                        live.console.print(table_formatter.get_border())
+                        stats_border_printed = True
+
+                exit_code = run_tlc(spec, callback=wrapped_callback, coverage=coverage)
+        else:
+            # Non-TTY mode: no Live block
+            table_formatter = StatsTableFormatter()
+            print(f"Starting TLC model checker (version {tlc_version}).")
 
             def wrapped_callback(res: ModelCheckResult) -> None:
+                nonlocal printed_logs_count, printed_stats_count, stats_header_printed, stats_border_printed
+
+                # Keep tests happy by updating the formatter
                 formatter.update(layout, res)
 
                 if not final_result:
@@ -113,8 +181,42 @@ def tlc(  # noqa: PLR0912, PLR0915
                 else:
                     final_result[0] = res
 
+                # Stream any new logs
+                if len(res.output_lines) > printed_logs_count:
+                    new_logs = res.output_lines[printed_logs_count:]
+                    for log in new_logs:
+                        print(log.strip())
+                    printed_logs_count = len(res.output_lines)
+
+                # Stream any new progress stats
+                if len(res.initial_states_stat) > printed_stats_count:
+                    new_stats = res.initial_states_stat[printed_stats_count:]
+                    for stat in new_stats:
+                        if not stats_header_printed:
+                            print("\nState Space Progress:\n")
+                            print(table_formatter.get_header())
+                            print(table_formatter.get_border())
+                            stats_header_printed = True
+
+                        row_str = table_formatter.format_row(stat)
+                        print(row_str)
+                    printed_stats_count = len(res.initial_states_stat)
+
+                # Print bottom border when execution changes state to non-running
+                if res.state != CheckState.Running and stats_header_printed and not stats_border_printed:
+                    print(table_formatter.get_border())
+                    stats_border_printed = True
+
             exit_code = run_tlc(spec, callback=wrapped_callback, coverage=coverage)
 
+        # Fallback print of border if not printed yet
+        if stats_header_printed and not stats_border_printed:
+            if is_tty:
+                console.print(table_formatter.get_border())
+            else:
+                print(table_formatter.get_border())
+            stats_border_printed = True
+
         if final_result:
             res = final_result[0]
 

{tlaplus_cli-0.6.0 → tlaplus_cli-0.7.0}/src/tlaplus_cli/java/classpath.py

@@ -84,7 +84,7 @@ class ClasspathResolver:
 
         return None
 
-    def _resolve_paths(self, cli_paths: list[str], subdir: SubdirType, config_path: str | None) -> list[str]:
+    def _resolve_paths(self, cli_paths: list[str], subdir: SubdirType, config_path: str | None) -> list[str]:  # noqa: PLR0912
         """
         Resolves a set of paths following the hierarchy.
         Deduplicates while preserving order.
@@ -106,10 +106,19 @@ class ClasspathResolver:
         # 4. Managed Modules (Global Cache)
         managed_dir = get_modules_dir()
         if managed_dir.is_dir():
-            # Add all subdirectories of managed_dir to raw_paths so they are expanded for JARs
-            for item in managed_dir.iterdir():
+            # Add all subdirectories of managed_dir to raw_paths so they are expanded for JARs/TLA files
+            for item in sorted(managed_dir.iterdir()):
                 if item.is_dir():
-                    raw_paths.append(str(item.absolute()))
+                    if subdir == SubdirType.LIB:
+                        mod_lib = item / "lib"
+                        if mod_lib.is_dir():
+                            raw_paths.append(str(mod_lib.absolute()))
+                        raw_paths.append(str(item.absolute()))  # Legacy fallback
+                    elif subdir == SubdirType.MODULES:
+                        mod_modules = item / "modules"
+                        if mod_modules.is_dir():
+                            raw_paths.append(str(mod_modules.absolute()))
+                        raw_paths.append(str(item.absolute()))  # Legacy fallback
 
         # Deduplicate while preserving order
         seen = set()
@@ -141,10 +150,24 @@ class ClasspathResolver:
 
         # In RUNTIME mode, custom classes shadow everything
         if mode == ResolveMode.RUNTIME:
+            # Project-local classes
             classes_dir = self.get_project_path(SubdirType.CLASSES)
             if classes_dir:
                 classpath.append(str(classes_dir.absolute()))
 
+            # Module source directories containing .tla files
+            modules = self._resolve_paths(self.extra_modules, SubdirType.MODULES, self.config.module_path)
+            classpath.extend(modules)
+
+        # Cached module classes are included as dependencies in all modes (RUNTIME & COMPILE)
+        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():
+                        classpath.append(str(mod_classes.absolute()))
+
         # Tool JAR
         if self.tool_jar:
             classpath.append(str(self.tool_jar.absolute()))

tlaplus_cli-0.7.0/src/tlaplus_cli/tlc/compiler.py

@@ -0,0 +1,12 @@
+from pathlib import Path
+
+from tlaplus_cli.config.loader import cache_dir
+from tlaplus_cli.versioning import get_pinned_version_dir
+
+
+def get_tlc_jar_path() -> Path:
+    """Resolve the path to tla2tools.jar using the fallback chain: pinned -> legacy."""
+    pinned_dir = get_pinned_version_dir()
+    pinned_jar = pinned_dir / "tla2tools.jar" if pinned_dir else None
+    legacy = cache_dir() / "tla2tools.jar"
+    return pinned_jar if (pinned_jar and pinned_jar.exists()) else legacy