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

tlaplus_cli-0.2.1/MANIFEST.in

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tlaplus-cli
-Version: 0.1.7
+Version: 0.2.1
 Summary: TLA+ tools: download TLC, compile custom modules, run model checker
 Author-email: Denis Nikolskiy <codeomatics@gmail.com>
 License-Expression: MIT
@@ -32,10 +32,10 @@ Command-line tool for working with TLA+ specifications and the TLC model checker
 
 ## Installation
 
-Install system-wide via uv tool
+Install system-wide via uv tool:
 
 ```bash
-uv tool install git+https://github.com/nikolskiy/tlaplus-cli
+uv tool install tlaplus-cli
 ```
 
 Upgrade:
@@ -43,51 +43,119 @@ Upgrade:
 uv tool upgrade tlaplus-cli
 ```
 
-Uninstall
-
+Uninstall:
 ```bash
 uv tool uninstall tlaplus-cli
 ```
 
 ## Usage
 
-### Download TLC
+### Managing TLC Versions
+
+The `tla tlc` command group allows you to download and manage multiple versions of the TLC model checker directly from GitHub releases. 
 
+List available and installed TLC versions:
 ```bash
-# Download stable release
-tla download
+tla tlc list
+```
 
-# Download nightly build
-tla download --nightly
+Install the latest TLC version:
+```bash
+tla tlc install
 ```
 
-### Check Java Version
+Install a specific TLC version:
+```bash
+tla tlc install v1.8.0
+```
 
+Pin a specific version to be used by default:
 ```bash
-tla check-java
+tla tlc pin v1.8.0
+```
+
+Upgrade the pinned version (or a specific version) to a newer commit:
+```bash
+tla tlc upgrade
 ```
 
+Show the TLC2 version string and absolute path to the pinned version's `tla2tools.jar`:
+```bash
+tla tlc path
+```
+
+Or for a specific version:
+```bash
+tla tlc 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
+```
+
+Show the TLC versions directory and all installed version directories:
+```bash
+tla tlc dir
+```
+
+Example output:
+```text
+/home/bob/.cache/tla/tlc
+  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
+```
+
+### Run TLC
+
+Run the TLC model checker on a specification. This uses the currently pinned TLC version.
+
+```bash
+tla run <spec_name>
+```
+
+For example (runs `queue.tla`):
+
+```bash
+tla run 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>`.
+
 ### Compile Custom Java Modules
 
+Note that modules are compiled using the pinned version of TLC.
+
+Compile modules:
 ```bash
 tla build
+```
 
-# Verbose output
+Verbose output:
+```bash
 tla build --verbose
 ```
 
 Compiles `.java` files from `workspace/modules/` into `workspace/classes/`.
 
-### Run TLC
+### Check Java Version
 
 ```bash
-tla tlc <spec_name>
+tla check-java
 ```
 
-For example:
+### Cache Management
+
+The CLI caches GitHub API responses for 1 hour to prevent rate limiting. To clear this cache manually:
 
 ```bash
-tla tlc queue
+tla fetch-cache clear
 ```
 
 ## Configuration
@@ -102,10 +170,9 @@ 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
+    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)
@@ -129,7 +196,8 @@ java:
 | Directory | Purpose | Location |
 |---|---|---|
 | Config | `config.yaml` | `~/.config/tla/` |
-| Cache | `tla2tools.jar` | `~/.cache/tla/` |
+| TLC Versions | Version dirs & `tlc-pinned-version.txt` file | `~/.cache/tla/tlc/` |
+| API Cache | `github_cache.json` | `~/.cache/tla/` |
 | Workspace | specs + modules + classes | Set via `workspace.root` in config |
 
 ## Note on Package Name

tlaplus_cli-0.2.1/README.md

@@ -0,0 +1,182 @@
+# 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 TLC Versions
+
+The `tla tlc` command group allows you to download and manage multiple versions of the TLC model checker directly from GitHub releases. 
+
+List available and installed TLC versions:
+```bash
+tla tlc list
+```
+
+Install the latest TLC version:
+```bash
+tla tlc install
+```
+
+Install a specific TLC version:
+```bash
+tla tlc install v1.8.0
+```
+
+Pin a specific version to be used by default:
+```bash
+tla tlc pin v1.8.0
+```
+
+Upgrade the pinned version (or a specific version) to a newer commit:
+```bash
+tla tlc upgrade
+```
+
+Show the TLC2 version string and absolute path to the pinned version's `tla2tools.jar`:
+```bash
+tla tlc path
+```
+
+Or for a specific version:
+```bash
+tla tlc 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
+```
+
+Show the TLC versions directory and all installed version directories:
+```bash
+tla tlc dir
+```
+
+Example output:
+```text
+/home/bob/.cache/tla/tlc
+  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
+```
+
+### Run TLC
+
+Run the TLC model checker on a specification. This uses the currently pinned TLC version.
+
+```bash
+tla run <spec_name>
+```
+
+For example (runs `queue.tla`):
+
+```bash
+tla run 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>`.
+
+### Compile Custom Java Modules
+
+Note that modules are compiled using the pinned version of TLC.
+
+Compile modules:
+```bash
+tla build
+```
+
+Verbose output:
+```bash
+tla build --verbose
+```
+
+Compiles `.java` files from `workspace/modules/` into `workspace/classes/`.
+
+### 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/` |
+| TLC Versions | Version dirs & `tlc-pinned-version.txt` file | `~/.cache/tla/tlc/` |
+| 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.1.7 → tlaplus_cli-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tlaplus-cli"
-version = "0.1.7"
+version = "0.2.1"
 description = "TLA+ tools: download TLC, compile custom modules, run model checker"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -37,13 +37,14 @@ 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"
+tla = "tlaplus_cli.cli:main"
 
 [tool.setuptools.packages.find]
-include = ["tla*"]
+where = ["src"]
+include = ["tlaplus_cli*"]
 
 [tool.setuptools.package-data]
-tla = ["resources/default_config.yaml", "py.typed"]
+tlaplus_cli = ["resources/default_config.yaml", "py.typed"]
 
 [dependency-groups]
 dev = [
@@ -62,7 +63,7 @@ dev = [
 ]
 
 [tool.pytest.ini_options]
-addopts = "--cov=tla --cov-report=term-missing"
+addopts = "--cov=tlaplus_cli --cov-report=term-missing"
 testpaths = ["tests"]
 
 [tool.ruff]

{tlaplus_cli-0.1.7/tla → tlaplus_cli-0.2.1/src/tlaplus_cli}/build_tlc_module.py

@@ -4,7 +4,8 @@ import subprocess
 
 import typer
 
-from tla.config import cache_dir, load_config, workspace_root
+from tlaplus_cli.config import cache_dir, load_config, workspace_root
+from tlaplus_cli.version_manager import get_pinned_version_dir
 
 
 def build(
@@ -13,16 +14,19 @@ def build(
     """Compile custom Java modules."""
     config = load_config()
 
-    # Jar lives in the cache directory
-    jar_path = cache_dir() / config.tla.jar_name
+    # Fallback chain: pinned directory -> legacy jar
+    pinned_dir = get_pinned_version_dir()
+    pinned_jar = pinned_dir / "tla2tools.jar" if pinned_dir else None
+    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(f"Error: {config.tla.jar_name} not found at {jar_path}", err=True)
-        typer.echo("Run 'tla download tla' first.", err=True)
+        typer.echo("Error: tla2tools.jar not found.", err=True)
+        typer.echo("Run 'tla tlc install' first.", err=True)
         raise typer.Exit(1)
 
     if not modules_dir.exists():

{tlaplus_cli-0.1.7/tla → tlaplus_cli-0.2.1/src/tlaplus_cli}/cli.py

@@ -4,11 +4,11 @@ import importlib.metadata
 
 import typer
 
-from tla.build_tlc_module import build as build_tlc_cmd
-from tla.check_java import check_java_version, get_java_version
-from tla.config import load_config
-from tla.download_tla2tools import tla as download_tla_cmd
-from tla.run_tlc import tlc as run_tlc_cmd
+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
 
 app = typer.Typer(
     name="tla",
@@ -47,10 +47,11 @@ def root(
 
 # --- Subcommands ---
 
-# Register 'download' directly as a command, effectively 'tla download'
-app.command(name="download")(download_tla_cmd)
+# Attach typer subgroups for TLC and fetch-cache
+app.add_typer(tlc_app, name="tlc")
+app.add_typer(fetch_cache_app, name="fetch-cache")
 
-app.command(name="tlc")(run_tlc_cmd)
+app.command(name="run")(run_tlc_cmd)
 app.command(name="build")(build_tlc_cmd)
 
 

{tlaplus_cli-0.1.7/tla → tlaplus_cli-0.2.1/src/tlaplus_cli}/config.py

@@ -5,7 +5,7 @@ from pathlib import Path
 import platformdirs
 import yaml
 
-from tla.settings import Settings
+from tlaplus_cli.settings import Settings
 
 _APP_NAME = "tla"
 

{tlaplus_cli-0.1.7/tla → tlaplus_cli-0.2.1/src/tlaplus_cli}/resources/default_config.yaml

@@ -1,8 +1,8 @@
 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
+    tags: https://api.github.com/repos/tlaplus/tlaplus/tags
+    releases: https://api.github.com/repos/tlaplus/tlaplus/releases
+    per_page: 30
 
 # Path to the TLA+ workspace (specs, custom modules, compiled classes).
 # Relative paths are resolved from the current working directory.

tlaplus_cli-0.2.1/src/tlaplus_cli/run_tlc.py

@@ -0,0 +1,86 @@
+"""Run TLC model checker on a TLA+ specification."""
+
+import os
+import subprocess
+
+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.version_manager import get_pinned_version_dir
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        config = load_config()
+        pinned_dir = get_pinned_version_dir()
+        pinned_jar = pinned_dir / "tla2tools.jar" if pinned_dir else None
+        legacy = cache_dir() / "tla2tools.jar"
+        jar_path = pinned_jar if (pinned_jar and pinned_jar.exists()) else legacy
+        typer.echo(f"tla2tools.jar path: {jar_path}")
+
+        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)
+            raise typer.Exit(1)
+
+        cmd = ["java", "-cp", str(jar_path), config.tlc.java_class]
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+            output = result.stdout or result.stderr
+            if output:
+                first_line = output.splitlines()[0]
+                typer.echo(first_line)
+        except FileNotFoundError as err:
+            typer.echo("Error: java not found.", err=True)
+            raise typer.Exit(1) from err
+
+        raise typer.Exit(0)
+
+
+def tlc(
+    spec: str = typer.Argument(help="Name of the TLA+ specification (without .tla extension)."),
+    version: bool | None = typer.Option(
+        None,
+        "--version",
+        help="Print the path to tla2tools.jar and its version.",
+        callback=version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Run TLC model checker on a TLA+ specification."""
+    if version:
+        pass
+    config = load_config()
+
+    check_java_version(config.java.min_version)
+
+    # Fallback chain: pinned version → legacy jar
+    pinned_dir = get_pinned_version_dir()
+    pinned_jar = pinned_dir / "tla2tools.jar" if pinned_dir else None
+    legacy = cache_dir() / "tla2tools.jar"
+    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)
+        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}"
+
+    cmd = ["java", *config.java.opts, "-cp", classpath, config.tlc.java_class, str(spec_file)]
+
+    typer.echo(f"Running TLC on {spec}.tla ...")
+    typer.echo(f"Command: {' '.join(cmd)}")
+    result = subprocess.run(cmd, cwd=str(spec_dir))
+    raise typer.Exit(result.returncode)

{tlaplus_cli-0.1.7/tla → tlaplus_cli-0.2.1/src/tlaplus_cli}/settings.py

@@ -6,12 +6,12 @@ from pydantic import BaseModel, Field, model_validator
 
 
 class TlaUrls(BaseModel):
-    stable: str
-    nightly: str
+    tags: str
+    releases: str
+    per_page: int = 30
 
 
 class TlaConfig(BaseModel):
-    jar_name: str
     urls: TlaUrls