tlaplus-cli 0.1.8__tar.gz → 0.3.1__tar.gz

{tlaplus_cli-0.1.8/src/tlaplus_cli.egg-info → tlaplus_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tlaplus-cli
-Version: 0.1.8
+Version: 0.3.1
 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
@@ -32,7 +33,7 @@ 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 tlaplus-cli
@@ -43,51 +44,131 @@ Upgrade:
 uv tool upgrade tlaplus-cli
 ```
 
-Uninstall
-
+Uninstall:
 ```bash
 uv tool uninstall tlaplus-cli
 ```
 
 ## Usage
 
-### Download TLC
+### 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
-# Download stable release
-tla download
+tla tools list
+```
 
-# Download nightly build
-tla download --nightly
+Install the latest toolset version:
+```bash
+tla tools install
 ```
 
-### Check Java 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 check-java
+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 TLC2 version string and 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
+TLC2 Version 2.19 of 08 August 2024 (rev: 5a47802)
+/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
+```
+
+> **Note:** Starting from version `0.3.0`, the command structure has changed. To run a model, use `tla tlc <spec>`. For version `0.2.x`, the command was `tla run <spec>`. Since `0.3.0`, management commands are under `tla tools`.
+
 ### Compile Custom Java Modules
 
+Note that modules are compiled using the pinned version of the toolset.
+
+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 +183,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 +209,8 @@ java:
 | Directory | Purpose | Location |
 |---|---|---|
 | Config | `config.yaml` | `~/.config/tla/` |
-| Cache | `tla2tools.jar` | `~/.cache/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

tlaplus_cli-0.3.1/README.md

@@ -0,0 +1,194 @@
+# 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 TLC2 version string and 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
+TLC2 Version 2.19 of 08 August 2024 (rev: 5a47802)
+/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
+```
+
+> **Note:** Starting from version `0.3.0`, the command structure has changed. To run a model, use `tla tlc <spec>`. For version `0.2.x`, the command was `tla run <spec>`. Since `0.3.0`, management commands are under `tla tools`.
+
+### Compile Custom Java Modules
+
+Note that modules are compiled using the pinned version of the toolset.
+
+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/` |
+| 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.1.8 → tlaplus_cli-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tlaplus-cli"
-version = "0.1.8"
+version = "0.3.1"
 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"}

tlaplus_cli-0.3.1/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.1.8 → tlaplus_cli-0.3.1}/src/tlaplus_cli/build_tlc_module.py

@@ -5,6 +5,7 @@ import subprocess
 import typer
 
 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.8 → tlaplus_cli-0.3.1}/src/tlaplus_cli/cli.py

@@ -7,12 +7,12 @@ import typer
 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.download_tla2tools import tla as download_tla_cmd
 from tlaplus_cli.run_tlc import tlc as run_tlc_cmd
+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,8 +47,9 @@ def root(
 
 # --- Subcommands ---
 
-# Register 'download' directly as a command, effectively 'tla download'
-app.command(name="download")(download_tla_cmd)
+# Attach typer subgroups for tools and fetch-cache
+app.add_typer(tools_app, name="tools")
+app.add_typer(fetch_cache_app, name="fetch-cache")
 
 app.command(name="tlc")(run_tlc_cmd)
 app.command(name="build")(build_tlc_cmd)

{tlaplus_cli-0.1.8 → tlaplus_cli-0.3.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.1.8 → tlaplus_cli-0.3.1}/src/tlaplus_cli/run_tlc.py

@@ -7,17 +7,21 @@ 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()
-        jar_path = cache_dir() / config.tla.jar_name
-        typer.echo(f"{config.tla.jar_name} path: {jar_path}")
+        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: {config.tla.jar_name} not found at {jar_path}", err=True)
-            typer.echo("Run 'tla download' first.", err=True)
+            typer.echo(f"Error: tla2tools.jar not found at {jar_path}", 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]
@@ -49,14 +53,17 @@ def tlc(
         pass
     config = load_config()
 
-    # Check Java version before proceeding
     check_java_version(config.java.min_version)
 
-    # Jar lives in the cache directory
-    jar_path = cache_dir() / config.tla.jar_name
+    # 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(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 tools install' first.", err=True)
         raise typer.Exit(1)
 
     ws_root = workspace_root()

{tlaplus_cli-0.1.8 → tlaplus_cli-0.3.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