tlaplus-cli 0.2.1__tar.gz → 0.3.2__tar.gz

{tlaplus_cli-0.2.1/src/tlaplus_cli.egg-info → tlaplus_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tlaplus-cli
-Version: 0.2.1
+Version: 0.3.2
 Summary: TLA+ tools: download TLC, compile custom modules, run model checker
 Author-email: Denis Nikolskiy <codeomatics@gmail.com>
 License-Expression: MIT
@@ -24,6 +24,7 @@ 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
 Dynamic: license-file
 
 # TLA+ CLI
@@ -50,99 +51,135 @@ uv tool uninstall tlaplus-cli
 
 ## Usage
 
-### Managing TLC Versions
+### Managing TLA+ Tools
 
-The `tla tlc` command group allows you to download and manage multiple versions of the TLC model checker directly from GitHub releases. 
+The `tla tools` command group allows you to download and manage multiple versions of the TLA+ toolset (TLC, SANY, TLATeX) directly from GitHub releases. 
 
-List available and installed TLC versions:
+List available and installed toolset versions:
 ```bash
-tla tlc list
+tla tools list
 ```
 
-Install the latest TLC version:
+Install the latest toolset version:
 ```bash
-tla tlc install
+tla tools install
 ```
 
-Install a specific TLC version:
+> [!TIP]
+> The first version you install is automatically "pinned" as the default. Subsequent installs won't change your pin unless you manually use `tla tools pin`.
+
+Install a specific toolset version:
 ```bash
-tla tlc install v1.8.0
+tla tools install v1.8.0
 ```
 
 Pin a specific version to be used by default:
 ```bash
-tla tlc pin v1.8.0
+tla tools pin v1.8.0
 ```
 
 Upgrade the pinned version (or a specific version) to a newer commit:
 ```bash
-tla tlc upgrade
+tla tools upgrade
 ```
 
-Show the TLC2 version string and absolute path to the pinned version's `tla2tools.jar`:
+> [!NOTE]
+> If the target version to upgrade is not yet installed locally, the CLI will automatically download it.
+
+Show the absolute path to the pinned version's `tla2tools.jar`:
 ```bash
-tla tlc path
+tla tools path
 ```
 
 Or for a specific version:
 ```bash
-tla tlc path v1.8.0
+tla tools path v1.8.0
 ```
 
 Example output:
 ```text
-TLC2 Version 2.19 of 08 August 2024 (rev: 5a47802)
-/home/bob/.cache/tla/tlc/v1.8.0-5a47802/tla2tools.jar
+/home/bob/.cache/tla/tools/v1.8.0-5a47802/tla2tools.jar
 ```
 
-Show the TLC versions directory and all installed version directories:
+Show the toolset versions directory and all installed version directories:
 ```bash
-tla tlc dir
+tla tools dir
 ```
 
 Example output:
 ```text
-/home/bob/.cache/tla/tlc
+/home/bob/.cache/tla/tools
   v1.7.0-abc1234
   v1.8.0-5a47802
 ```
 
 Uninstall a specific version (or use 'default' to remove legacy jars):
 ```bash
-tla tlc uninstall v1.8.0
+tla tools uninstall v1.8.0
 ```
 
+> [!TIP]
+> Use `--all` to remove all installed tags for a specific version name without interactive prompts.
+
+> [!NOTE]
+> If you uninstall the currently pinned version, the CLI will automatically "fall back" to the next best installed version (ranked by semver, then release date).
+
 ### Run TLC
 
-Run the TLC model checker on a specification. This uses the currently pinned TLC version.
+Run the TLC model checker on a specification. This uses the currently pinned toolset version.
 
 ```bash
-tla run <spec_name>
+tla tlc <spec_name>
 ```
 
 For example (runs `queue.tla`):
 
 ```bash
-tla run queue
+tla tlc queue
 ```
 
-> **Note:** Starting from version `0.2.0`, the command structure has changed. To run a model, use `tla run <spec>`. For older versions (<0.2.0), the command was `tla tlc <spec>`.
+#### Project-Aware Execution
+
+The CLI intelligently resolves the specification file and its project structure. It will check the following locations:
+1.  `<spec_name>` (if it's a direct path to a file, e.g., `models/my_model.tla`)
+2.  `<spec_name>.tla`
+3.  `spec/<spec_name>.tla` (checks an inner `spec/` folder relative to the spec's location)
+
+Furthermore, it automatically discovers the **project root** by looking for `modules/`, `classes/`, or `lib/` directories adjacent to the spec file or its parent. When a project root is found:
+- The project's `classes/` directory is added to the Java classpath.
+- Any `*.jar` files found in the project's `lib/` directory are added to the Java classpath.
+- The `-DTLA-Library` system property is set to the project's `modules/` directory, allowing TLC to find your custom Java overrides.
+
+To check the currently pinned `tla2tools.jar` path and its TLC version:
+
+```bash
+tla tlc --version
+```
 
 ### Compile Custom Java Modules
 
-Note that modules are compiled using the pinned version of TLC.
+Java modules (overrides) are compiled using the pinned version of the toolset.
+
+Compile modules in the current project:
+```bash
+tla modules build
+```
 
-Compile modules:
+Compile modules in a specific project path:
 ```bash
-tla build
+tla modules build path/to/project
 ```
 
 Verbose output:
 ```bash
-tla build --verbose
+tla modules build --verbose
 ```
 
-Compiles `.java` files from `workspace/modules/` into `workspace/classes/`.
+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.
+3. Compiles `.java` files from the project's `modules/` directory into its `classes/` directory.
+4. Generates the necessary Java service provider configuration for TLC overrides.
 
 ### Check Java Version
 
@@ -196,7 +233,7 @@ java:
 | Directory | Purpose | Location |
 |---|---|---|
 | Config | `config.yaml` | `~/.config/tla/` |
-| TLC Versions | Version dirs & `tlc-pinned-version.txt` file | `~/.cache/tla/tlc/` |
+| Toolset Versions | Version dirs & `tools-pinned-version.txt` file | `~/.cache/tla/tools/` |
 | API Cache | `github_cache.json` | `~/.cache/tla/` |
 | Workspace | specs + modules + classes | Set via `workspace.root` in config |
 

tlaplus_cli-0.3.2/README.md

@@ -0,0 +1,218 @@
+# 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 tlaplus-cli
+```
+
+Upgrade:
+```bash
+uv tool upgrade tlaplus-cli
+```
+
+Uninstall:
+```bash
+uv tool uninstall tlaplus-cli
+```
+
+## Usage
+
+### Managing TLA+ Tools
+
+The `tla tools` command group allows you to download and manage multiple versions of the TLA+ toolset (TLC, SANY, TLATeX) directly from GitHub releases. 
+
+List available and installed toolset versions:
+```bash
+tla tools list
+```
+
+Install the latest toolset version:
+```bash
+tla tools install
+```
+
+> [!TIP]
+> The first version you install is automatically "pinned" as the default. Subsequent installs won't change your pin unless you manually use `tla tools pin`.
+
+Install a specific toolset version:
+```bash
+tla tools install v1.8.0
+```
+
+Pin a specific version to be used by default:
+```bash
+tla tools pin v1.8.0
+```
+
+Upgrade the pinned version (or a specific version) to a newer commit:
+```bash
+tla tools upgrade
+```
+
+> [!NOTE]
+> If the target version to upgrade is not yet installed locally, the CLI will automatically download it.
+
+Show the absolute path to the pinned version's `tla2tools.jar`:
+```bash
+tla tools path
+```
+
+Or for a specific version:
+```bash
+tla tools path v1.8.0
+```
+
+Example output:
+```text
+/home/bob/.cache/tla/tools/v1.8.0-5a47802/tla2tools.jar
+```
+
+Show the toolset versions directory and all installed version directories:
+```bash
+tla tools dir
+```
+
+Example output:
+```text
+/home/bob/.cache/tla/tools
+  v1.7.0-abc1234
+  v1.8.0-5a47802
+```
+
+Uninstall a specific version (or use 'default' to remove legacy jars):
+```bash
+tla tools uninstall v1.8.0
+```
+
+> [!TIP]
+> Use `--all` to remove all installed tags for a specific version name without interactive prompts.
+
+> [!NOTE]
+> If you uninstall the currently pinned version, the CLI will automatically "fall back" to the next best installed version (ranked by semver, then release date).
+
+### Run TLC
+
+Run the TLC model checker on a specification. This uses the currently pinned toolset version.
+
+```bash
+tla tlc <spec_name>
+```
+
+For example (runs `queue.tla`):
+
+```bash
+tla tlc queue
+```
+
+#### Project-Aware Execution
+
+The CLI intelligently resolves the specification file and its project structure. It will check the following locations:
+1.  `<spec_name>` (if it's a direct path to a file, e.g., `models/my_model.tla`)
+2.  `<spec_name>.tla`
+3.  `spec/<spec_name>.tla` (checks an inner `spec/` folder relative to the spec's location)
+
+Furthermore, it automatically discovers the **project root** by looking for `modules/`, `classes/`, or `lib/` directories adjacent to the spec file or its parent. When a project root is found:
+- The project's `classes/` directory is added to the Java classpath.
+- Any `*.jar` files found in the project's `lib/` directory are added to the Java classpath.
+- The `-DTLA-Library` system property is set to the project's `modules/` directory, allowing TLC to find your custom Java overrides.
+
+To check the currently pinned `tla2tools.jar` path and its TLC version:
+
+```bash
+tla tlc --version
+```
+
+### Compile Custom Java Modules
+
+Java modules (overrides) are compiled using the pinned version of the toolset.
+
+Compile modules in the current project:
+```bash
+tla modules build
+```
+
+Compile modules in a specific project path:
+```bash
+tla modules build path/to/project
+```
+
+Verbose output:
+```bash
+tla modules build --verbose
+```
+
+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.
+3. Compiles `.java` files from the project's `modules/` directory into its `classes/` directory.
+4. Generates the necessary Java service provider configuration for TLC overrides.
+
+### Check Java Version
+
+```bash
+tla check-java
+```
+
+### Cache Management
+
+The CLI caches GitHub API responses for 1 hour to prevent rate limiting. To clear this cache manually:
+
+```bash
+tla fetch-cache clear
+```
+
+## 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:
+  urls:
+    tags: https://api.github.com/repos/tlaplus/tlaplus/tags
+    releases: https://api.github.com/repos/tlaplus/tlaplus/releases
+
+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/` |
+| Toolset Versions | Version dirs & `tools-pinned-version.txt` file | `~/.cache/tla/tools/` |
+| API Cache | `github_cache.json` | `~/.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.2.1 → tlaplus_cli-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tlaplus-cli"
-version = "0.2.1"
+version = "0.3.2"
 description = "TLA+ tools: download TLC, compile custom modules, run model checker"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -14,6 +14,7 @@ dependencies = [
     "pyyaml>=6.0,<7.0",
     "platformdirs>=4.0,<5.0",
     "pydantic>=2.12.5,<3.0.0",
+    "truststore>=0.9.0,<1.0.0",
 ]
 authors = [
     {name = "Denis Nikolskiy", email = "codeomatics@gmail.com"}
@@ -100,6 +101,7 @@ ignore = [
 [tool.ruff.lint.per-file-ignores]
 "tests/*" = [
     "ARG001", # Unused arguments are common in tests (fixtures)
+    "PLR0913", # Many arguments are common in tests (fixtures)
 ]
 
 [tool.poe.tasks]

tlaplus_cli-0.3.2/src/tlaplus_cli/__init__.py

@@ -0,0 +1,6 @@
+import truststore
+
+# Inject truststore as early as possible so that all standard library
+# and third-party tools relying on `ssl` (such as `requests` and `urllib3`)
+# utilize the native OS trust store.
+truststore.inject_into_ssl()

{tlaplus_cli-0.2.1 → tlaplus_cli-0.3.2}/src/tlaplus_cli/build_tlc_module.py

@@ -1,6 +1,8 @@
 """Compile custom TLC modules (Java)."""
 
+import os
 import subprocess
+from pathlib import Path
 
 import typer
 
@@ -9,10 +11,12 @@ from tlaplus_cli.version_manager import get_pinned_version_dir
 
 
 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."),
 ) -> None:
     """Compile custom Java modules."""
     config = load_config()
+    base_dir = Path(path).resolve() if path is not None else workspace_root()
 
     # Fallback chain: pinned directory -> legacy jar
     pinned_dir = get_pinned_version_dir()
@@ -20,31 +24,29 @@ def build(
     legacy = cache_dir() / "tla2tools.jar"
     jar_path = pinned_jar if (pinned_jar and pinned_jar.exists()) else legacy
 
-    ws_root = workspace_root()
-    modules_dir = ws_root / config.workspace.modules_dir
-    classes_dir = ws_root / config.workspace.classes_dir
-
     if not jar_path.exists():
-        typer.echo("Error: tla2tools.jar not found.", err=True)
-        typer.echo("Run 'tla tlc install' first.", err=True)
+        typer.echo("Error: tla2tools.jar not found.\nRun 'tla tools install' first.", err=True)
         raise typer.Exit(1)
 
+    modules_dir = base_dir / config.workspace.modules_dir
+    classes_dir = base_dir / config.workspace.classes_dir
+
+    lib_dir = base_dir / "lib"
+    lib_jars = sorted(lib_dir.glob("*.jar")) if lib_dir.is_dir() else []
+    classpath = os.pathsep.join([str(jar_path)] + [str(j) for j in lib_jars])
+
     if not modules_dir.exists():
         typer.echo(f"Error: modules directory not found: {modules_dir}", err=True)
         raise typer.Exit(1)
 
-    # Find all .java files in modules dir
     java_files = list(modules_dir.rglob("*.java"))
     if not java_files:
         typer.echo(f"No Java source files found in {modules_dir}", err=True)
         return
 
     typer.echo(f"Compiling {len(java_files)} Java files from {modules_dir} ...")
-
-    # Ensure output dir exists
     classes_dir.mkdir(parents=True, exist_ok=True)
-
-    cmd = ["javac", "-cp", str(jar_path), "-d", str(classes_dir), *[str(f) for f in java_files]]
+    cmd = ["javac", "-cp", classpath, "-d", str(classes_dir), *[str(f) for f in java_files]]
 
     try:
         result = subprocess.run(cmd, check=True, capture_output=not verbose, text=True)
@@ -52,14 +54,11 @@ def build(
         if verbose and result.stdout:
             typer.echo(result.stdout)
 
-        # Create META-INF/services/tlc2.overrides.ITLCOverrides
         meta_inf = classes_dir / "META-INF" / "services"
         meta_inf.mkdir(parents=True, exist_ok=True)
         service_file = meta_inf / "tlc2.overrides.ITLCOverrides"
-
         with service_file.open("w") as f:
             f.write(f"{config.tlc.overrides_class}\n")
-
         typer.echo(f"Created service file at {service_file}")
 
     except subprocess.CalledProcessError as e:

{tlaplus_cli-0.2.1 → tlaplus_cli-0.3.2}/src/tlaplus_cli/cli.py

@@ -8,11 +8,11 @@ from tlaplus_cli.build_tlc_module import build as build_tlc_cmd
 from tlaplus_cli.check_java import check_java_version, get_java_version
 from tlaplus_cli.config import load_config
 from tlaplus_cli.run_tlc import tlc as run_tlc_cmd
-from tlaplus_cli.tlc_manager import fetch_cache_app, tlc_app
+from tlaplus_cli.tools_manager import fetch_cache_app, tools_app
 
 app = typer.Typer(
     name="tla",
-    help="TLA+ tools: download TLC, compile custom modules, run model checker.",
+    help="TLA+ tools: download TLA+ toolset distribution, compile custom modules, run model checker.",
     no_args_is_help=True,
     add_completion=False,
 )
@@ -47,12 +47,15 @@ def root(
 
 # --- Subcommands ---
 
-# Attach typer subgroups for TLC and fetch-cache
-app.add_typer(tlc_app, name="tlc")
+# Attach typer subgroups
+modules_app = typer.Typer(name="modules", help="Manage TLA+ Java modules.", no_args_is_help=True)
+modules_app.command(name="build")(build_tlc_cmd)
+
+app.add_typer(modules_app, name="modules")
+app.add_typer(tools_app, name="tools")
 app.add_typer(fetch_cache_app, name="fetch-cache")
 
-app.command(name="run")(run_tlc_cmd)
-app.command(name="build")(build_tlc_cmd)
+app.command(name="tlc")(run_tlc_cmd)
 
 
 @app.command(name="check-java")

tlaplus_cli-0.3.2/src/tlaplus_cli/project.py

@@ -0,0 +1,35 @@
+"""Project root discovery utilities."""
+
+from pathlib import Path
+
+
+def _is_project_root(directory: Path, modules_dir: Path | str, classes_dir: Path | str, lib_dir: Path | str) -> bool:
+    """Return True if directory contains at least one project structure marker."""
+    return (
+        (directory / classes_dir).is_dir()
+        or (directory / modules_dir).is_dir()
+        or (directory / lib_dir).is_dir()
+    )
+
+
+def find_project_root(
+    spec_file: Path,
+    *,
+    modules_dir: Path | str,
+    classes_dir: Path | str,
+    lib_dir: Path | str = "lib",
+) -> Path | None:
+    """Resolve the project root relative to a .tla spec file.
+
+    Resolution strategy (in order):
+    1. Check the spec file's own directory.
+    2. Check the parent of the spec file's directory (handles spec/ and tests/ subdirs).
+    3. Return None if neither directory qualifies.
+    """
+    spec_dir = spec_file.parent.resolve()
+
+    for candidate in (spec_dir, spec_dir.parent):
+        if _is_project_root(candidate, modules_dir, classes_dir, lib_dir):
+            return candidate
+
+    return None

{tlaplus_cli-0.2.1 → tlaplus_cli-0.3.2}/src/tlaplus_cli/run_tlc.py

@@ -2,11 +2,13 @@
 
 import os
 import subprocess
+from pathlib import Path
 
 import typer
 
 from tlaplus_cli.check_java import check_java_version
-from tlaplus_cli.config import cache_dir, load_config, workspace_root
+from tlaplus_cli.config import cache_dir, load_config
+from tlaplus_cli.project import find_project_root
 from tlaplus_cli.version_manager import get_pinned_version_dir
 
 
@@ -21,7 +23,7 @@ def version_callback(value: bool) -> None:
 
         if not jar_path.exists():
             typer.echo(f"Error: tla2tools.jar not found at {jar_path}", err=True)
-            typer.echo("Run 'tla tlc install' first.", err=True)
+            typer.echo("Run 'tla tools install' first.", err=True)
             raise typer.Exit(1)
 
         cmd = ["java", "-cp", str(jar_path), config.tlc.java_class]
@@ -62,25 +64,42 @@ def tlc(
     jar_path = pinned_jar if (pinned_jar and pinned_jar.exists()) else legacy
 
     if not jar_path.exists():
-        typer.echo("Error: tla2tools.jar not found.", err=True)
-        typer.echo("Run 'tla tlc install' first.", err=True)
+        typer.echo("Error: tla2tools.jar not found.\nRun 'tla tools install' first.", err=True)
         raise typer.Exit(1)
 
-    ws_root = workspace_root()
-    spec_dir = ws_root / config.workspace.spec_dir
-    spec_file = spec_dir / f"{spec}.tla"
-    if not spec_file.exists():
-        typer.echo(f"Error: specification not found: {spec_file}", err=True)
-        raise typer.Exit(1)
-
-    classpath = str(jar_path)
-    classes_path = ws_root / config.workspace.classes_dir
-    if classes_path.exists():
-        classpath = f"{classes_path}{os.pathsep}{classpath}"
+    # Spec resolution logic
+    spec_path = Path(spec)
+    candidates = [spec_path, spec_path.with_suffix(".tla"),
+                  spec_path.parent / "spec" / (spec_path.name + ".tla")]
 
-    cmd = ["java", *config.java.opts, "-cp", classpath, config.tlc.java_class, str(spec_file)]
+    spec_file = next((c for c in candidates if c.is_file()), None)
+    if not spec_file:
+        typer.echo("Error: Could not find a TLA+ spec file. Looked in the following locations:", err=True)
+        for c in candidates:
+            typer.echo(f"- {c}", err=True)
+        raise typer.Exit(1)
 
-    typer.echo(f"Running TLC on {spec}.tla ...")
-    typer.echo(f"Command: {' '.join(cmd)}")
-    result = subprocess.run(cmd, cwd=str(spec_dir))
+    spec_file = spec_file.absolute()
+    project_root = find_project_root(
+        spec_file, modules_dir=config.workspace.modules_dir, classes_dir=config.workspace.classes_dir
+    )
+
+    classpath_parts = [str(jar_path)]
+    extra_jvm_opts: list[str] = []
+    if project_root:
+        classes_path = project_root / config.workspace.classes_dir
+        if classes_path.is_dir():
+            classpath_parts.insert(0, str(classes_path))
+        lib_dir = project_root / "lib"
+        if lib_dir.is_dir():
+            classpath_parts.extend(str(j) for j in sorted(lib_dir.glob("*.jar")))
+        modules_path = project_root / config.workspace.modules_dir
+        if modules_path.is_dir():
+            extra_jvm_opts.append(f"-DTLA-Library={modules_path}")
+
+    cmd = ["java", *config.java.opts, *extra_jvm_opts, "-cp", os.pathsep.join(classpath_parts),
+           config.tlc.java_class, spec_file.name]
+
+    typer.echo(f"Running TLC on {spec_file.name} ...\nCommand: {' '.join(cmd)}")
+    result = subprocess.run(cmd, cwd=str(spec_file.parent))
     raise typer.Exit(result.returncode)