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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tlaplus-cli
-Version: 0.3.5
+Version: 0.4.1
 Summary: TLA+ tools: download TLC, compile custom modules, run model checker
 Author-email: Denis Nikolskiy <codeomatics@gmail.com>
 License-Expression: MIT
@@ -175,8 +175,25 @@ Configure a persistent custom modules path:
 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
+```
+
+Configure a persistent custom modules dependencies (lib) path:
+```bash
+tla modules lib /path/to/custom/libs
+```
+
+View or reset the custom lib path:
+```bash
+tla modules lib          # View current path
+tla modules lib none     # Reset to default
+```
+
 > [!TIP]
-> Setting a persistent `module_path` allows `tla modules build` and `tla tlc` to resolve your Java overrides regardless of where the commands are executed.
+> Setting a persistent `module_path` (and optionally `module_lib_path`) allows `tla modules build` and `tla tlc` to resolve your Java overrides regardless of where the commands are executed.
 
 Verbose output:
 ```bash
@@ -211,7 +228,15 @@ On first run, a default config is created at:
 ~/.config/tla/config.yaml
 ```
 
-Edit this file to set your workspace path and TLC options:
+You can manage the configuration using the `tla config` command:
+
+```bash
+tla config list          # Display current configuration
+tla config edit          # Open config in default editor ($EDITOR or vim)
+tla config edit nano     # Open config in a specific editor
+```
+
+Example configuration (`config.yaml`):
 
 ```yaml
 tla:
@@ -230,6 +255,7 @@ tlc:
   overrides_class: tlc2.overrides.TLCOverrides
 
 module_path: null         # (Optional) Persistent custom modules path
+module_lib_path: null     # (Optional) Persistent custom modules lib path
 
 java:
   min_version: 11

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

@@ -146,8 +146,25 @@ Configure a persistent custom modules path:
 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
+```
+
+Configure a persistent custom modules dependencies (lib) path:
+```bash
+tla modules lib /path/to/custom/libs
+```
+
+View or reset the custom lib path:
+```bash
+tla modules lib          # View current path
+tla modules lib none     # Reset to default
+```
+
 > [!TIP]
-> Setting a persistent `module_path` allows `tla modules build` and `tla tlc` to resolve your Java overrides regardless of where the commands are executed.
+> Setting a persistent `module_path` (and optionally `module_lib_path`) allows `tla modules build` and `tla tlc` to resolve your Java overrides regardless of where the commands are executed.
 
 Verbose output:
 ```bash
@@ -182,7 +199,15 @@ On first run, a default config is created at:
 ~/.config/tla/config.yaml
 ```
 
-Edit this file to set your workspace path and TLC options:
+You can manage the configuration using the `tla config` command:
+
+```bash
+tla config list          # Display current configuration
+tla config edit          # Open config in default editor ($EDITOR or vim)
+tla config edit nano     # Open config in a specific editor
+```
+
+Example configuration (`config.yaml`):
 
 ```yaml
 tla:
@@ -201,6 +226,7 @@ tlc:
   overrides_class: tlc2.overrides.TLCOverrides
 
 module_path: null         # (Optional) Persistent custom modules path
+module_lib_path: null     # (Optional) Persistent custom modules lib path
 
 java:
   min_version: 11

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tlaplus-cli"
-version = "0.3.5"
+version = "0.4.1"
 description = "TLA+ tools: download TLC, compile custom modules, run model checker"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -62,6 +62,7 @@ dev = [
     "pre-commit>=3.5.0,<4.0.0",
     "pre-commit-hooks>=6.0.0,<7.0.0",
     "twine>=6.0.0,<7.0.0",
+    "bandit>=1.9.4",
 ]
 
 [tool.pytest.ini_options]
@@ -105,10 +106,14 @@ ignore = [
     "PLR0913", # Many arguments are common in tests (fixtures)
 ]
 
+[tool.bandit]
+skips = ["B404", "B603", "B607"]
+
 [tool.poe.tasks]
 check = "pre-commit run --all-files"
-lint = ["lint-ruff", "type-check"]
+lint = ["lint-ruff", "lint-bandit", "type-check"]
 lint-ruff = "ruff check ."
+lint-bandit = "bandit -c pyproject.toml -r src/tlaplus_cli"
 type-check = "mypy ."
 fix = ["format", "lint-fix"]
 format = "ruff format ."

tlaplus_cli-0.4.1/src/tlaplus_cli/cache/github.py

@@ -0,0 +1,28 @@
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+from tlaplus_cli.ui import warn
+from tlaplus_cli.versioning.schema import RemoteVersion
+
+
+def load_github_cache(cache_file: Path) -> list[RemoteVersion] | None:
+    """Load the remote versions cache from disk."""
+    if cache_file.exists():
+        try:
+            with cache_file.open("r", encoding="utf-8") as f:
+                data = json.load(f)
+            return [RemoteVersion(**item) for item in data]
+        except (json.JSONDecodeError, OSError, KeyError, TypeError) as e:
+            warn(f"Failed to read cache: {e}")
+    return None
+
+
+def save_github_cache(cache_file: Path, versions: list[RemoteVersion]) -> None:
+    """Save the remote versions cache to disk."""
+    try:
+        cache_file.parent.mkdir(parents=True, exist_ok=True)
+        with cache_file.open("w", encoding="utf-8") as f:
+            json.dump([asdict(v) for v in versions], f)
+    except OSError as e:
+        warn(f"Failed to save cache: {e}")

tlaplus_cli-0.4.1/src/tlaplus_cli/cli.py

@@ -0,0 +1,60 @@
+"""TLA+ CLI tool - entry point."""
+
+import importlib.metadata
+
+import typer
+
+from tlaplus_cli.cmd.check_java import check_java
+from tlaplus_cli.cmd.config import app as config_app
+from tlaplus_cli.cmd.fetch_cache import app as fetch_cache_app
+from tlaplus_cli.cmd.modules import app as modules_app
+from tlaplus_cli.cmd.tlc import tlc as run_tlc_cmd
+from tlaplus_cli.cmd.tools import app as tools_app
+from tlaplus_cli.config.loader import load_config
+
+app = typer.Typer(
+    name="tla",
+    help="TLA+ tools: download TLA+ toolset distribution, compile custom modules, run model checker.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        meta = importlib.metadata.metadata("tlaplus-cli")
+        typer.echo(f"{meta['Name']} v{meta['Version']}")
+        typer.echo(meta["Summary"])
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    version: bool = typer.Option(  # noqa: ARG001
+        None,
+        "--version",
+        "-v",
+        help="Show the application's version and exit.",
+        callback=version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """TLA+ CLI tool."""
+    # Load config early to trigger first-run copy
+    load_config()
+
+
+# --- Subcommands ---
+
+app.add_typer(modules_app, name="modules")
+app.add_typer(tools_app, name="tools")
+app.add_typer(fetch_cache_app, name="fetch-cache")
+app.add_typer(config_app, name="config")
+
+app.command(name="tlc")(run_tlc_cmd)
+app.command(name="check-java")(check_java)
+
+
+def main() -> None:
+    """Entry point for [project.scripts]."""
+    app()

tlaplus_cli-0.4.1/src/tlaplus_cli/cmd/check_java.py

@@ -0,0 +1,19 @@
+import typer
+
+from tlaplus_cli.config.loader import load_config
+from tlaplus_cli.java import get_java_version, validate_java_version
+
+
+def check_java() -> None:
+    """Check if Java is installed and meets the minimum version requirement."""
+    config = load_config()
+    version = get_java_version()
+    if version:
+        typer.echo(f"Detected Java version: {version}")
+
+    try:
+        validate_java_version(config.java.min_version)
+        typer.echo(f"Java version is compatible (>= {config.java.min_version}).")
+    except RuntimeError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1) from None

tlaplus_cli-0.4.1/src/tlaplus_cli/cmd/config/__init__.py

@@ -0,0 +1,6 @@
+import typer
+
+app = typer.Typer(name="config", help="Manage application configuration.", no_args_is_help=True)
+
+from . import edit  # noqa: F401, E402
+from . import list as list_cmd  # noqa: F401, E402

tlaplus_cli-0.4.1/src/tlaplus_cli/cmd/config/edit.py

@@ -0,0 +1,34 @@
+import os
+import shutil
+import subprocess
+
+import typer
+
+from tlaplus_cli.cmd.config import app
+from tlaplus_cli.config.loader import config_path, load_config
+
+
+@app.command(name="edit")
+def edit_config(
+    editor: str | None = typer.Argument(None, help="The editor to use (defaults to $EDITOR or 'vim')."),
+) -> None:
+    """Open the configuration file in an editor."""
+    cp = config_path()
+
+    # Ensure config exists by loading it
+    load_config()
+
+    if not editor:
+        editor = os.environ.get("EDITOR", "vim")
+
+    editor_path = shutil.which(editor)
+    if not editor_path:
+        typer.echo(f"Error: Editor '{editor}' not found in PATH.", err=True)
+        raise typer.Exit(1)
+
+    typer.echo(f"Opening {cp} with {editor} ...")
+    try:
+        subprocess.run([editor_path, str(cp)], check=True)
+    except subprocess.CalledProcessError as e:
+        typer.echo(f"Editor exited with error: {e}", err=True)
+        raise typer.Exit(1) from None

tlaplus_cli-0.4.1/src/tlaplus_cli/cmd/config/list.py

@@ -0,0 +1,16 @@
+import typer
+
+from tlaplus_cli.cmd.config import app
+from tlaplus_cli.config.loader import config_path
+
+
+@app.command(name="list")
+def list_config() -> None:
+    """Display the current configuration file content."""
+    cp = config_path()
+    if not cp.exists():
+        typer.echo("Configuration file not found.", err=True)
+        raise typer.Exit(1)
+
+    with cp.open(encoding="utf-8") as f:
+        typer.echo(f.read())

tlaplus_cli-0.4.1/src/tlaplus_cli/cmd/fetch_cache/__init__.py

@@ -0,0 +1,5 @@
+import typer
+
+app = typer.Typer(name="fetch-cache", help="Manage API fetch cache.", no_args_is_help=True)
+
+from . import clear  # noqa: F401, E402

tlaplus_cli-0.4.1/src/tlaplus_cli/cmd/fetch_cache/clear.py

@@ -0,0 +1,11 @@
+import typer
+
+from tlaplus_cli.cmd.fetch_cache import app
+from tlaplus_cli.versioning import clear_cache
+
+
+@app.command(name="clear")
+def cmd_clear_cache() -> None:
+    """Clear the local cache of remote GitHub versions."""
+    clear_cache()
+    typer.echo("GitHub versions cache cleared.")

tlaplus_cli-0.4.1/src/tlaplus_cli/cmd/modules/__init__.py

@@ -0,0 +1,5 @@
+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

tlaplus_cli-0.4.1/src/tlaplus_cli/cmd/modules/build.py

@@ -0,0 +1,30 @@
+import subprocess
+from pathlib import Path
+
+import typer
+
+from tlaplus_cli.cmd.modules import app
+from tlaplus_cli.tlc.compiler import 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."),
+) -> None:
+    """Compile custom Java modules."""
+    base_dir = Path(path).resolve() if path is not None else None
+
+    typer.echo("Compiling Java files ...")
+    try:
+        classes_dir = compile_modules(base_dir, verbose)
+    except FileNotFoundError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1) from None
+    except subprocess.CalledProcessError:
+        typer.echo("Compilation failed!", err=True)
+        raise typer.Exit(1) from None
+
+    typer.echo(f"Successfully compiled to {classes_dir}")
+    service_file = classes_dir / "META-INF" / "services" / "tlc2.overrides.ITLCOverrides"
+    typer.echo(f"Created service file at {service_file}")

tlaplus_cli-0.4.1/src/tlaplus_cli/cmd/modules/lib.py

@@ -0,0 +1,46 @@
+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
+
+
+@app.command(name="lib")
+def set_modules_lib_path(
+    path: str | None = typer.Argument(
+        None, help="Path to the custom Java modules dependencies directory, or 'none' to reset."
+    ),
+) -> None:
+    """Configure or view a persistent custom Java modules dependencies (lib) path."""
+    config_obj = load_config()
+
+    if path is None:
+        if config_obj.module_lib_path:
+            typer.echo(f"Current modules lib path: {config_obj.module_lib_path}")
+        else:
+            modules_dir = (
+                Path(config_obj.module_path)
+                if config_obj.module_path
+                else workspace_root() / config_obj.workspace.modules_dir
+            )
+            default_path = modules_dir / "lib"
+            typer.echo("Custom modules lib path is not set.")
+            typer.echo(f"Defaulting to: {default_path}")
+        return
+
+    if path.lower() == "none":
+        config_obj.module_lib_path = None
+        save_config(config_obj)
+        typer.echo("Custom modules lib 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_lib_path = str(p)
+    save_config(config_obj)
+    typer.echo(f"Modules lib path updated to: {p}")

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

@@ -0,0 +1,39 @@
+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
+
+
+@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."),
+) -> None:
+    """Configure or view a persistent custom Java modules source path."""
+    config_obj = load_config()
+
+    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.4.1/src/tlaplus_cli/cmd/tlc.py

@@ -0,0 +1,51 @@
+import typer
+
+from tlaplus_cli.tlc.compiler import get_tlc_jar_path
+from tlaplus_cli.tlc.runner import 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():
+            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)
+
+        version_str = get_tlc_version()
+        if version_str:
+            typer.echo(version_str)
+
+        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
+
+    try:
+        _, spec_name = resolve_spec_file(spec)
+    except FileNotFoundError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1) from None
+
+    typer.echo(f"Running TLC on {spec_name} ...")
+    try:
+        exit_code = run_tlc(spec)
+    except FileNotFoundError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1) from None
+
+    raise typer.Exit(exit_code)

tlaplus_cli-0.4.1/src/tlaplus_cli/cmd/tools/__init__.py

@@ -0,0 +1,8 @@
+import typer
+
+from tlaplus_cli.cmd.tools.meta import app as meta_app
+
+app = typer.Typer(name="tools", help="Manage TLC tools (tla2tools.jar).", no_args_is_help=True)
+app.add_typer(meta_app, name="meta")
+
+from . import dir, install, list, path, pin, uninstall, upgrade  # noqa: F401, E402

tlaplus_cli-0.4.1/src/tlaplus_cli/cmd/tools/dir.py

@@ -0,0 +1,16 @@
+import typer
+
+from tlaplus_cli.cmd.tools import app
+from tlaplus_cli.versioning import get_tools_dir
+
+
+@app.command(name="dir")
+def show_dir() -> None:
+    """Show the absolute path to the local TLC tools cache directory."""
+    tools_dir = get_tools_dir()
+    typer.echo(str(tools_dir))
+
+    if tools_dir.is_dir():
+        versions = sorted([d.name for d in tools_dir.iterdir() if d.is_dir()])
+        for v in versions:
+            typer.echo(f"  {v}")

tlaplus_cli-0.4.1/src/tlaplus_cli/cmd/tools/install.py

@@ -0,0 +1,79 @@
+from pathlib import Path
+
+import requests
+import typer
+
+from tlaplus_cli.cmd.tools import app
+from tlaplus_cli.config.loader import load_config
+from tlaplus_cli.versioning import (
+    download_version,
+    download_version_from_url,
+    fetch_remote_versions,
+    get_pinned_version_dir,
+    get_tools_dir,
+    is_url,
+    set_pin,
+)
+
+
+def _auto_pin_if_needed(version_dir: Path) -> None:
+    """Pin the version if no version is currently pinned."""
+    pinned_dir = get_pinned_version_dir()
+    if pinned_dir is None:
+        typer.echo(f"Auto-pinning newly installed version {version_dir.name}")
+        set_pin(version_dir)
+
+
+@app.command()
+def install(
+    version: str = typer.Argument(None, help="Version tag (e.g. 'v1.8.0') or a direct URL to tla2tools.jar."),
+    force: bool = typer.Option(False, "--force", "-f", help="Re-download if already installed."),
+) -> None:
+    """Download and install a specific TLC version."""
+    if version and is_url(version):
+        try:
+            version_dir = download_version_from_url(version)
+        except (requests.RequestException, OSError, ValueError) as e:
+            typer.echo(f"Error: Failed to download: {e}", err=True)
+            raise typer.Exit(1) from e
+        else:
+            typer.echo("Download complete.")
+            typer.echo(f"Successfully installed from URL to {version_dir}")
+            _auto_pin_if_needed(version_dir)
+            return
+
+    config = load_config()
+    versions, status = fetch_remote_versions(config.tla.urls.tags, config.tla.urls.releases, config.tla.urls.per_page)
+
+    if not versions:
+        typer.echo(f"Error: Could not fetch remote versions (status: {status.value})", err=True)
+        raise typer.Exit(1)
+
+    target = None
+    if version:
+        target = next((v for v in versions if v.name == version), None)
+        if not target:
+            typer.echo(f"Error: Version {version} not found.", err=True)
+            raise typer.Exit(1)
+    else:
+        typer.echo("No version specified, selecting latest stable release.")
+        # Default to latest non-prerelease
+        target = next((v for v in versions if not v.prerelease), versions[0])
+
+    # Check if already installed
+    target_dir = get_tools_dir() / f"{target.name}-{target.short_sha}"
+    if target_dir.exists() and not force:
+        typer.echo(f"Version {target.name} is already installed.")
+        typer.echo(f"Successfully installed {target.name} to {target_dir}")
+        _auto_pin_if_needed(target_dir)
+        return
+
+    try:
+        version_dir = download_version(target, force=force)
+        typer.echo("Download complete.")
+        typer.echo(f"Successfully installed {target.name} to {version_dir}")
+    except (requests.RequestException, OSError) as e:
+        typer.echo(f"Error: Failed to download: {e}", err=True)
+        raise typer.Exit(1) from e
+
+    _auto_pin_if_needed(version_dir)