tlaplus-cli 0.4.1__tar.gz → 0.5.0__tar.gz

{tlaplus_cli-0.4.1/src/tlaplus_cli.egg-info → tlaplus_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tlaplus-cli
-Version: 0.4.1
+Version: 0.5.0
 Summary: TLA+ tools: download TLC, compile custom modules, run model checker
 Author-email: Denis Nikolskiy <codeomatics@gmail.com>
 License-Expression: MIT
@@ -156,6 +156,12 @@ To check the currently pinned `tla2tools.jar` path and its TLC version:
 tla tlc --version
 ```
 
+To inspect the exact Java command that will be executed without running it:
+
+```bash
+tla tlc <spec_name> --show-command
+```
+
 ### Compile Custom Java Modules
 
 Java modules (overrides) are compiled using the pinned version of the toolset.
@@ -177,8 +183,9 @@ tla modules path /path/to/custom/modules
 
 View or reset the custom modules path:
 ```bash
-tla modules path         # View current path
-tla modules path none    # Reset to default
+tla modules path          # View current path
+tla modules path none     # Reset to default
+tla modules path --resolved  # Show fully resolved paths for current context
 ```
 
 Configure a persistent custom modules dependencies (lib) path:
@@ -200,6 +207,11 @@ Verbose output:
 tla modules build --verbose
 ```
 
+Show compilation command:
+```bash
+tla modules build --show-command
+```
+
 The build command:
 1. Resolves the project root (defaults to `workspace.root` from config).
 2. Includes `lib/*.jar` files from the project root in the `javac` classpath.

{tlaplus_cli-0.4.1 → tlaplus_cli-0.5.0}/README.md

@@ -127,6 +127,12 @@ To check the currently pinned `tla2tools.jar` path and its TLC version:
 tla tlc --version
 ```
 
+To inspect the exact Java command that will be executed without running it:
+
+```bash
+tla tlc <spec_name> --show-command
+```
+
 ### Compile Custom Java Modules
 
 Java modules (overrides) are compiled using the pinned version of the toolset.
@@ -148,8 +154,9 @@ tla modules path /path/to/custom/modules
 
 View or reset the custom modules path:
 ```bash
-tla modules path         # View current path
-tla modules path none    # Reset to default
+tla modules path          # View current path
+tla modules path none     # Reset to default
+tla modules path --resolved  # Show fully resolved paths for current context
 ```
 
 Configure a persistent custom modules dependencies (lib) path:
@@ -171,6 +178,11 @@ Verbose output:
 tla modules build --verbose
 ```
 
+Show compilation command:
+```bash
+tla modules build --show-command
+```
+
 The build command:
 1. Resolves the project root (defaults to `workspace.root` from config).
 2. Includes `lib/*.jar` files from the project root in the `javac` classpath.

{tlaplus_cli-0.4.1 → tlaplus_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tlaplus-cli"
-version = "0.4.1"
+version = "0.5.0"
 description = "TLA+ tools: download TLC, compile custom modules, run model checker"
 readme = "README.md"
 requires-python = ">=3.11"

{tlaplus_cli-0.4.1 → tlaplus_cli-0.5.0}/src/tlaplus_cli/cli.py

@@ -30,7 +30,7 @@ def version_callback(value: bool) -> None:
 
 @app.callback()
 def root(
-    version: bool = typer.Option(  # noqa: ARG001
+    _: bool = typer.Option(
         None,
         "--version",
         "-v",

{tlaplus_cli-0.4.1 → tlaplus_cli-0.5.0}/src/tlaplus_cli/cmd/modules/__init__.py

@@ -2,4 +2,4 @@ import typer
 
 app = typer.Typer(name="modules", help="Manage TLA+ Java modules.", no_args_is_help=True)
 
-from . import build, lib, path  # noqa: F401, E402
+from . import build, install, lib, path  # noqa: F401, E402

{tlaplus_cli-0.4.1 → tlaplus_cli-0.5.0}/src/tlaplus_cli/cmd/modules/build.py

@@ -4,17 +4,28 @@ from pathlib import Path
 import typer
 
 from tlaplus_cli.cmd.modules import app
-from tlaplus_cli.tlc.compiler import compile_modules
+from tlaplus_cli.tlc.compiler import build_compile_command, compile_modules
 
 
 @app.command(name="build")
 def build(
     path: str | None = typer.Argument(None, help="Project root directory (defaults to workspace root)."),
     verbose: bool = typer.Option(False, "--verbose", "-v", help="Show compilation output."),
+    show_command: bool = typer.Option(False, "--show-command", help="Print the command instead of executing it."),
 ) -> None:
     """Compile custom Java modules."""
     base_dir = Path(path).resolve() if path is not None else None
 
+    if show_command:
+        try:
+            cmd = build_compile_command(base_dir)
+        except FileNotFoundError as e:
+            typer.echo(f"Error: {e}", err=True)
+            raise typer.Exit(1) from None
+        if cmd:
+            typer.echo(" ".join(cmd))
+        return
+
     typer.echo("Compiling Java files ...")
     try:
         classes_dir = compile_modules(base_dir, verbose)

tlaplus_cli-0.5.0/src/tlaplus_cli/cmd/modules/install.py

@@ -0,0 +1,75 @@
+import requests
+import typer
+
+from tlaplus_cli import ui
+from tlaplus_cli.cmd.modules import app
+from tlaplus_cli.config.loader import load_config
+from tlaplus_cli.versioning import (
+    download_version,
+    download_version_from_url,
+    fetch_remote_versions,
+    is_url,
+)
+from tlaplus_cli.versioning.paths import get_modules_dir
+
+
+@app.command(name="install-community")
+def install_community(
+    version: str = typer.Argument(
+        None, help="Version tag (e.g. 'v202412171801') or a direct URL to CommunityModules.jar."
+    ),
+    force: bool = typer.Option(False, "--force", "-f", help="Re-download if already installed."),
+) -> None:
+    """Download and install a specific version of CommunityModules."""
+    base_dir = get_modules_dir()
+    jar_name = "CommunityModules.jar"
+
+    if version and is_url(version):
+        try:
+            version_dir = download_version_from_url(version, base_dir=base_dir, jar_name=jar_name)
+        except (requests.RequestException, OSError, ValueError) as e:
+            ui.error(f"Failed to download: {e}")
+            raise typer.Exit(1) from e
+        else:
+            ui.success(f"Successfully installed from URL to {version_dir}")
+            return
+
+    config = load_config()
+    if not config.tla.community_modules:
+        ui.error("Community modules URLs not configured in settings.")
+        raise typer.Exit(1)
+
+    versions, status = fetch_remote_versions(
+        config.tla.community_modules.tags,
+        config.tla.community_modules.releases,
+        config.tla.community_modules.per_page,
+        asset_name=jar_name,
+    )
+
+    if not versions:
+        ui.error(f"Could not fetch remote versions (status: {status.value})")
+        raise typer.Exit(1)
+
+    target = None
+    if version:
+        target = next((v for v in versions if v.name == version), None)
+        if not target:
+            ui.error(f"Version {version} not found.")
+            raise typer.Exit(1)
+    else:
+        # Default to latest non-prerelease
+        target = next((v for v in versions if not v.prerelease), versions[0])
+        ui.info(f"No version specified, selecting latest stable release: {target.name}")
+
+    # Check if already installed
+    target_dir = base_dir / f"{target.name}-{target.short_sha}"
+    if target_dir.exists() and not force:
+        ui.info(f"Version {target.name} is already installed at {target_dir}")
+        return
+
+    try:
+        version_dir = download_version(target, force=force, base_dir=base_dir, jar_name=jar_name)
+        ui.success(f"Successfully installed {target.name} to {version_dir}")
+    except (requests.RequestException, OSError) as e:
+        ui.error(f"Failed to download: {e}")
+        raise typer.Exit(1) from e

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

@@ -0,0 +1,72 @@
+from pathlib import Path
+
+import typer
+
+from tlaplus_cli.cmd.modules import app
+from tlaplus_cli.config.loader import load_config, save_config, workspace_root
+from tlaplus_cli.java.classpath import ClasspathResolver, ResolveMode, SubdirType
+from tlaplus_cli.tlc.compiler import get_tlc_jar_path
+
+
+@app.command(name="path")
+def set_modules_path(
+    path: str | None = typer.Argument(None, help="Path to the custom Java modules directory, or 'none' to reset."),
+    resolved: bool = typer.Option(False, "--resolved", help="Show the actual resolved paths for the current context."),
+) -> None:
+    """Configure or view custom Java modules source path."""
+    config_obj = load_config()
+
+    if resolved:
+        resolver = ClasspathResolver(config_obj, project_root=workspace_root(), tool_jar=get_tlc_jar_path())
+
+        # Source path (modules)
+        tla_library = resolver.get_tla_library_property()
+        typer.echo(f"Source Path: {tla_library or 'None'}")
+
+        # Classes path
+        classes_dir = resolver.get_project_path(SubdirType.CLASSES)
+        typer.echo(f"Classes Path: {classes_dir or 'None'}")
+
+        # Library path (JARs)
+        libs = resolver.resolve(ResolveMode.RUNTIME)
+        # Filter out classes_dir and tool_jar to show only libs
+        tool_jar = get_tlc_jar_path()
+        only_libs = [p for p in libs if p != str(classes_dir) and p != str(tool_jar)]
+
+        lib_str = "None"
+        if only_libs:
+            lib_str = f"{len(only_libs)} JARs"
+
+        typer.echo(f"Library Path: {lib_str}")
+        if only_libs:
+            for lib in only_libs:
+                typer.echo(f"  - {lib}")
+
+        # Tool Jar
+        typer.echo(f"Tool Jar: {tool_jar}")
+        return
+
+    if path is None:
+        if config_obj.module_path:
+            typer.echo(f"Current modules path: {config_obj.module_path}")
+        else:
+            default_path = workspace_root() / config_obj.workspace.modules_dir
+            typer.echo("Custom modules path is not set.")
+            typer.echo(f"Defaulting to: {default_path}")
+        return
+
+    if path.lower() == "none":
+        config_obj.module_path = None
+        save_config(config_obj)
+        typer.echo("Custom modules path reset to default.")
+        return
+
+    p = Path(path).resolve()
+
+    if not p.is_dir():
+        typer.echo(f"Error: Path does not exist or is not a directory: {p}", err=True)
+        raise typer.Exit(1)
+
+    config_obj.module_path = str(p)
+    save_config(config_obj)
+    typer.echo(f"Modules path updated to: {p}")

tlaplus_cli-0.5.0/src/tlaplus_cli/cmd/tlc.py

@@ -0,0 +1,139 @@
+import typer
+
+from tlaplus_cli import ui
+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.models import CheckState, CheckStatus, ModelCheckResult
+from tlaplus_cli.tlc.runner import (
+    build_tlc_command,
+    get_tlc_version,
+    resolve_spec_file,
+    run_tlc,
+)
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        jar_path = get_tlc_jar_path()
+        typer.echo(f"tla2tools.jar path: {jar_path}")
+
+        if not jar_path.exists():
+            ui.error(f"tla2tools.jar not found at {jar_path}")
+            typer.echo("Run 'tla tools install' first.", err=True)
+            raise typer.Exit(1)
+
+        version_str = get_tlc_version()
+        if version_str:
+            typer.echo(version_str)
+
+        raise typer.Exit(0)
+
+
+def print_progress(result: ModelCheckResult) -> None:
+    """Callback to print progress from ModelCheckResult."""
+    if result.status == CheckStatus.SuccessorStatesComputing and result.initial_states_stat:
+        last_stat = result.initial_states_stat[-1]
+        # Use carriage return to update the same line for progress
+        msg = f"Progress: {last_stat.total} states generated, {last_stat.distinct} distinct states found"
+        typer.echo(f"\r{msg}", err=True, nl=False)
+    elif result.status == CheckStatus.Finished:
+        # Final newline after progress
+        typer.echo("", err=True)
+
+
+def _show_diagnostic_info(spec: str, spec_name: str) -> None:
+    """Show diagnostic info before running TLC."""
+    version_str = get_tlc_version() or "unknown"
+    typer.echo(f"Running TLC ({version_str}) on {spec_name} ...")
+
+    # Check if we have TLA-Library
+    try:
+        config = load_config()
+        spec_file, _ = resolve_spec_file(spec)
+        project_root = find_project_root(
+            spec_file,
+            modules_dir=config.workspace.modules_dir,
+            classes_dir=config.workspace.classes_dir,
+        )
+        jar_path = get_tlc_jar_path()
+        resolver = ClasspathResolver(config, project_root=project_root, tool_jar=jar_path)
+        tla_library = resolver.get_tla_library_property()
+        if tla_library:
+            ui.info(f"TLA-Library: {tla_library}")
+    except Exception:
+        pass  # nosec
+
+
+# PLR0912: This command handler orchestrates multiple output types (errors, warnings, results, progress);
+# splitting it would fragment the CLI's primary user-facing logic.
+def tlc(  # noqa: PLR0912
+    spec: str = typer.Argument(help="Name of the TLA+ specification (without .tla extension)."),
+    # Typer requires the parameter in the signature to register the CLI option;
+    # since the logic is in the eager callback, the value is not used here.
+    version: bool | None = typer.Option(  # noqa: ARG001
+        None,
+        "--version",
+        help="Print the path to tla2tools.jar and its version.",
+        callback=version_callback,
+        is_eager=True,
+    ),
+    show_command: bool = typer.Option(False, "--show-command", help="Print the command instead of executing it."),
+) -> None:
+    """Run TLC model checker on a TLA+ specification."""
+    # version argument is handled by version_callback (is_eager=True)
+    try:
+        _, spec_name = resolve_spec_file(spec)
+    except FileNotFoundError as e:
+        ui.error(str(e))
+        raise typer.Exit(1) from None
+
+    if show_command:
+        try:
+            cmd = build_tlc_command(spec)
+        except FileNotFoundError as e:
+            ui.error(str(e))
+            raise typer.Exit(1) from None
+        typer.echo(" ".join(cmd))
+        raise typer.Exit(0)
+
+    _show_diagnostic_info(spec, spec_name)
+
+    try:
+        # We need the parser to get the final result, so we'll wrap run_tlc
+        # or capture the result from the last callback.
+        final_result: list[ModelCheckResult] = []
+
+        def wrapped_callback(res: ModelCheckResult) -> None:
+            print_progress(res)
+            if not final_result:
+                final_result.append(res)
+            else:
+                final_result[0] = res
+
+        exit_code = run_tlc(spec, callback=wrapped_callback)
+
+        if final_result:
+            res = final_result[0]
+            if res.state == CheckState.Success:
+                ui.success("Model checking completed successfully.")
+            elif res.state == CheckState.Error:
+                ui.error(f"Model checking failed with {len(res.errors)} error(s).")
+                for err in res.errors:
+                    for line in err.lines:
+                        typer.echo(f"  {line}", err=True)
+
+            if res.warnings:
+                ui.warn(f"Found {len(res.warnings)} warning(s).")
+                for warn_info in res.warnings:
+                    for line in warn_info.lines:
+                        typer.echo(f"  {line}", err=True)
+
+            if res.duration:
+                ui.info(f"Duration: {res.duration}ms")
+    except FileNotFoundError as e:
+        ui.error(str(e))
+        raise typer.Exit(1) from None
+
+    raise typer.Exit(exit_code)

{tlaplus_cli-0.4.1 → tlaplus_cli-0.5.0}/src/tlaplus_cli/cmd/tools/meta/sync.py

@@ -2,6 +2,7 @@ import typer
 
 from tlaplus_cli.cmd.tools.meta import app
 from tlaplus_cli.config.loader import load_config
+from tlaplus_cli.ui import warn
 from tlaplus_cli.versioning import (
     fetch_remote_versions,
     list_local_versions,
@@ -28,6 +29,6 @@ def meta_sync() -> None:
             write_version_metadata(lv.path, target)
             typer.echo(f"Synced metadata for {lv.path.name}")
         else:
-            typer.echo(f"⚠ Warning: Could not find remote data for {lv.name}", err=True)
+            warn(f"Could not find remote data for {lv.name}")
 
     typer.echo("Metadata sync complete.")

{tlaplus_cli-0.4.1 → tlaplus_cli-0.5.0}/src/tlaplus_cli/cmd/tools/uninstall.py

@@ -5,6 +5,7 @@ import typer
 
 from tlaplus_cli.cmd.tools import app
 from tlaplus_cli.config.loader import cache_dir
+from tlaplus_cli.ui import warn
 from tlaplus_cli.versioning import (
     clear_pin,
     get_pinned_version_dir,
@@ -24,12 +25,12 @@ def _resolve_uninstall_targets(versions: list[str]) -> list[Path]:
             if legacy.exists():
                 targets.append(legacy)
             else:
-                typer.echo("⚠ Warning: Default (legacy) tla2tools.jar not found.", err=True)
+                warn("Default (legacy) tla2tools.jar not found.")
             continue
 
         matching = sorted([lv for lv in local_versions if lv.name == v], key=lambda x: x.path.name)
         if not matching:
-            typer.echo(f"⚠ Warning: Version {v} not found locally.", err=True)
+            warn(f"Version {v} not found locally.")
             continue
 
         if len(matching) > 1:

{tlaplus_cli-0.4.1 → tlaplus_cli-0.5.0}/src/tlaplus_cli/config/schema.py

@@ -13,6 +13,7 @@ class TlaUrls(BaseModel):
 
 class TlaConfig(BaseModel):
     urls: TlaUrls
+    community_modules: TlaUrls | None = None
 
 
 class WorkspaceConfig(BaseModel):

tlaplus_cli-0.5.0/src/tlaplus_cli/java/classpath.py

@@ -0,0 +1,174 @@
+import os
+from enum import Enum, auto
+from pathlib import Path
+
+from tlaplus_cli.config.schema import Settings
+from tlaplus_cli.versioning.paths import get_modules_dir
+
+
+class ResolveMode(Enum):
+    """Modes for classpath resolution."""
+
+    RUNTIME = auto()  # For 'java -cp ... tlc2.TLC' (classes first)
+    COMPILE = auto()  # For 'javac -cp ...' (tool jar first, no output classes)
+
+
+class SubdirType(Enum):
+    """Types of project-local subdirectories."""
+
+    MODULES = auto()
+    CLASSES = auto()
+    LIB = auto()
+
+
+class ClasspathResolver:
+    """
+    Centralized component for resolving Java classpaths and system properties.
+    Follows a strict Specific-to-General hierarchy: CLI > Project > Config > Global.
+    """
+
+    def __init__(
+        self,
+        config: Settings,
+        project_root: Path | None = None,
+        tool_jar: Path | None = None,
+        extra_libs: list[str] | None = None,
+        extra_modules: list[str] | None = None,
+    ):
+        """
+        Initialize the resolver.
+
+        Args:
+            config: The global settings.
+            project_root: The root of the TLA+ project (where .tla file is).
+            tool_jar: Path to tla2tools.jar.
+            extra_libs: Explicit library paths from CLI.
+            extra_modules: Explicit module paths from CLI.
+        """
+        self.config = config
+        self.project_root = project_root
+        self.tool_jar = tool_jar
+        self.extra_libs = extra_libs or []
+        self.extra_modules = extra_modules or []
+
+    def get_project_path(self, subdir: SubdirType) -> Path | None:
+        """Helper to find a project-local directory."""
+        if not self.project_root:
+            return None
+
+        # 1. Try explicit workspace config mapping
+        if subdir == SubdirType.MODULES:
+            path = self.project_root / self.config.workspace.modules_dir
+            if path.is_dir():
+                return path
+        elif subdir == SubdirType.CLASSES:
+            path = self.project_root / self.config.workspace.classes_dir
+            if path.is_dir():
+                return path
+
+        # 2. Try direct subdir (new standard)
+        subdir_name = {
+            SubdirType.MODULES: "modules",
+            SubdirType.CLASSES: "classes",
+            SubdirType.LIB: "lib",
+        }[subdir]
+        path = self.project_root / subdir_name
+        if path.is_dir():
+            return path
+
+        # 3. Try legacy/nested 'lib' inside modules_dir
+        if subdir == SubdirType.LIB:
+            path = self.project_root / self.config.workspace.modules_dir / "lib"
+            if path.is_dir():
+                return path
+
+        return None
+
+    def _resolve_paths(self, cli_paths: list[str], subdir: SubdirType, config_path: str | None) -> list[str]:
+        """
+        Resolves a set of paths following the hierarchy.
+        Deduplicates while preserving order.
+        """
+        raw_paths = []
+
+        # 1. CLI Arguments
+        raw_paths.extend(cli_paths)
+
+        # 2. Project-Local
+        project_path = self.get_project_path(subdir)
+        if project_path:
+            raw_paths.append(str(project_path.absolute()))
+
+        # 3. Config
+        if config_path:
+            raw_paths.append(str(Path(config_path).absolute()))
+
+        # 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():
+                if item.is_dir():
+                    raw_paths.append(str(item.absolute()))
+
+        # Deduplicate while preserving order
+        seen = set()
+        deduped = []
+        for p in raw_paths:
+            # Expand directories to include JARs if it's a lib path
+            path_obj = Path(p)
+            if path_obj.is_dir() and subdir == SubdirType.LIB:
+                for jar in sorted(path_obj.glob("*.jar")):
+                    jar_abs = str(jar.absolute())
+                    if jar_abs not in seen:
+                        seen.add(jar_abs)
+                        deduped.append(jar_abs)
+            else:
+                p_abs = str(path_obj.absolute())
+                if p_abs not in seen:
+                    seen.add(p_abs)
+                    deduped.append(p_abs)
+
+        return deduped
+
+    def resolve(self, mode: ResolveMode) -> list[str]:
+        """
+        Resolve all necessary paths for the classpath based on the requested mode.
+        Deduplicates results while preserving the Specific-to-General order
+        and mode-specific requirements.
+        """
+        classpath = []
+
+        # In RUNTIME mode, custom classes shadow everything
+        if mode == ResolveMode.RUNTIME:
+            classes_dir = self.get_project_path(SubdirType.CLASSES)
+            if classes_dir:
+                classpath.append(str(classes_dir.absolute()))
+
+        # Tool JAR
+        if self.tool_jar:
+            classpath.append(str(self.tool_jar.absolute()))
+
+        # Libraries (CLI > Project > Config)
+        libs = self._resolve_paths(self.extra_libs, SubdirType.LIB, self.config.module_lib_path)
+        classpath.extend(libs)
+
+        # Final deduplication (e.g. if tool_jar is also in libs)
+        seen = set()
+        final_cp = []
+        for p in classpath:
+            if p not in seen:
+                seen.add(p)
+                final_cp.append(p)
+
+        return final_cp
+
+    def get_tla_library_property(self) -> str | None:
+        """
+        Resolve paths for -DTLA-Library system property.
+        Deduplicates, orders, and joins multiple valid directories.
+        """
+        modules = self._resolve_paths(self.extra_modules, SubdirType.MODULES, self.config.module_path)
+        if not modules:
+            return None
+        return os.pathsep.join(modules)

{tlaplus_cli-0.4.1 → tlaplus_cli-0.5.0}/src/tlaplus_cli/resources/default_config.yaml

@@ -3,6 +3,10 @@ tla:
     tags: https://api.github.com/repos/tlaplus/tlaplus/tags
     releases: https://api.github.com/repos/tlaplus/tlaplus/releases
     per_page: 30
+  community_modules:
+    tags: https://api.github.com/repos/tlaplus/CommunityModules/tags
+    releases: https://api.github.com/repos/tlaplus/CommunityModules/releases
+    per_page: 30
 
 # Path to the TLA+ workspace (specs, custom modules, compiled classes).
 # Relative paths are resolved from the current working directory.