tlaup 0.8.2__tar.gz

tlaup-0.8.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Nikolskiy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tlaup-0.8.2/MANIFEST.in

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

tlaup-0.8.2/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: tlaup
+Version: 0.8.2
+Summary: TLA+ tools: download TLC, compile custom modules, run model checker
+Author-email: Denis Nikolskiy <nikolskiy@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nikolskiy/tlaup
+Project-URL: Repository, https://github.com/nikolskiy/tlaup
+Project-URL: Issues, https://github.com/nikolskiy/tlaup/issues
+Project-URL: Changelog, https://github.com/nikolskiy/tlaup/blob/main/CHANGELOG.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer<1.0.0,>=0.22.0
+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
+Requires-Dist: rich<14.0.0,>=13.7.0
+Dynamic: license-file
+
+# tlaup
+
+Command-line tool for working with TLA+ specifications and the TLC model checker.
+
+> **Formerly `tlaplus-cli`.** The project, the PyPI package and the command were renamed to `tlaup` in 0.8.2.
+> The old `tla` command is gone; use `tlaup` instead. Installed toolsets, modules and config are kept where they were.
+
+## Project Goals
+
+1. Simplify managing TLA+ tools such as TLC, community modules, custom modules, etc.
+2. Run TLA tools in a single CLI interface.
+3. Manage and display the tool outputs.
+
+## Quick Start & Usage
+
+### 1. Toolset Management (`tlaup tools`)
+* `tlaup check-java`: Verify Java installation and compatibility.
+* `tlaup tools list`: List available and installed toolset versions (`tla2tools.jar`).
+* `tlaup tools install [vX.Y.Z]`: Download and install a toolset version.
+* `tlaup tools pin <version>`: Set default toolset version for TLC runs.
+
+### 2. Model Checking (`tlaup tlc`)
+* `tlaup tlc <spec>`: Execute TLC model checker on a specification.
+* `tlaup tlc <spec> --show-command`: Inspect exact JVM command before execution.
+
+### 3. Custom Java Modules (`tlaup modules`)
+* `tlaup modules add <path>`: Compile Java operator overrides and register module in CLI cache.
+* `tlaup modules list`: Display cached custom modules.
+* `tlaup modules remove <name>`: Remove custom module from cache.
+
+For complete, runnable specifications and Java module examples, see [docs/examples](docs/examples/).
+
+## Quick Installation
+
+### Via `uv tool`
+```bash
+uv tool install tlaup
+```
+
+If you installed the old package, remove it first:
+```bash
+uv tool uninstall tlaplus-cli
+```

tlaup-0.8.2/README.md

@@ -0,0 +1,43 @@
+# tlaup
+
+Command-line tool for working with TLA+ specifications and the TLC model checker.
+
+> **Formerly `tlaplus-cli`.** The project, the PyPI package and the command were renamed to `tlaup` in 0.8.2.
+> The old `tla` command is gone; use `tlaup` instead. Installed toolsets, modules and config are kept where they were.
+
+## Project Goals
+
+1. Simplify managing TLA+ tools such as TLC, community modules, custom modules, etc.
+2. Run TLA tools in a single CLI interface.
+3. Manage and display the tool outputs.
+
+## Quick Start & Usage
+
+### 1. Toolset Management (`tlaup tools`)
+* `tlaup check-java`: Verify Java installation and compatibility.
+* `tlaup tools list`: List available and installed toolset versions (`tla2tools.jar`).
+* `tlaup tools install [vX.Y.Z]`: Download and install a toolset version.
+* `tlaup tools pin <version>`: Set default toolset version for TLC runs.
+
+### 2. Model Checking (`tlaup tlc`)
+* `tlaup tlc <spec>`: Execute TLC model checker on a specification.
+* `tlaup tlc <spec> --show-command`: Inspect exact JVM command before execution.
+
+### 3. Custom Java Modules (`tlaup modules`)
+* `tlaup modules add <path>`: Compile Java operator overrides and register module in CLI cache.
+* `tlaup modules list`: Display cached custom modules.
+* `tlaup modules remove <name>`: Remove custom module from cache.
+
+For complete, runnable specifications and Java module examples, see [docs/examples](docs/examples/).
+
+## Quick Installation
+
+### Via `uv tool`
+```bash
+uv tool install tlaup
+```
+
+If you installed the old package, remove it first:
+```bash
+uv tool uninstall tlaplus-cli
+```

tlaup-0.8.2/pyproject.toml

@@ -0,0 +1,148 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tlaup"
+version = "0.8.2"
+description = "TLA+ tools: download TLC, compile custom modules, run model checker"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.22.0,<1.0.0",
+    "requests>=2.31.0,<3.0.0",
+    "pyyaml>=6.0,<7.0",
+    "platformdirs>=4.0,<5.0",
+    "pydantic>=2.12.5,<3.0.0",
+    "truststore>=0.9.0,<1.0.0",
+    "rich>=13.7.0,<14.0.0",
+]
+authors = [
+    {name = "Denis Nikolskiy", email = "nikolskiy@users.noreply.github.com"}
+]
+license = "MIT"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/nikolskiy/tlaup"
+Repository = "https://github.com/nikolskiy/tlaup"
+Issues = "https://github.com/nikolskiy/tlaup/issues"
+Changelog = "https://github.com/nikolskiy/tlaup/blob/main/CHANGELOG.md"
+
+[project.scripts]
+tlaup = "tlaup.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["tlaup*"]
+
+[tool.setuptools.package-data]
+tlaup = ["py.typed"]
+"tlaup.resources" = ["*.yaml"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2,<10.0.0",
+    "pytest-cov>=7.0.0,<8.0.0",
+    "pytest-mock>=3.15.1,<4.0.0",
+    "ruff>=0.9.0,<1.0.0",
+    "mypy>=1.0.0,<2.0.0",
+    "types-PyYAML>=6.0.12.12,<7.0.0.0",
+    "types-requests>=2.31.0.2,<3.0.0.0",
+    "poethepoet>=0.24.0,<1.0.0",
+    "detect-secrets>=1.5.0,<2.0.0",
+    "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]
+addopts = "--cov=tlaup --cov-report=term-missing"
+testpaths = ["tests/unit"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "F",      # Pyflakes: logic errors
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "I",      # isort: import sorting
+    "N",      # pep8-naming: naming conventions
+    "UP",     # pyupgrade: upgrade syntax for newer python versions
+    "PL",     # Pylint: various checks (convention, refactor, warning, etc.)
+    "B",      # flake8-bugbear: finds likely bugs and design problems
+    "SIM",    # flake8-simplify: suggests simpler python constructs
+    "C4",     # flake8-comprehensions: better list/set/dict comprehensions
+    "PIE",    # flake8-pie: miscellaneous lints
+    "TCH",    # flake8-type-checking: move imports to type-checking blocks
+    "PGH",    # pygrep-hooks: regex based checks
+    "G",      # flake8-logging-format: validate logging format strings
+    "RUF",    # Ruff-specific rules
+    "PTH",    # flake8-use-pathlib: replace os.path with pathlib
+    "ARG",    # flake8-unused-arguments: find unused function arguments
+    "RET",    # flake8-return: cleaner return logic
+    "TRY",    # tryceratops: prevent exception handling anti-patterns
+]
+ignore = [
+    "PLR2004", # Magic value used in comparison
+    "PLW1510", # subprocess.run without explicit check
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "ARG001", # Unused arguments are common in tests (fixtures)
+    "PLR0913", # Many arguments are common in tests (fixtures)
+    "PLR0917", # Many positional arguments are common in tests (fixtures)
+]
+
+[tool.bandit]
+skips = ["B404", "B603", "B607"]
+
+[tool.poe.tasks]
+check = "pre-commit run --all-files"
+lint = ["lint-ruff", "lint-bandit", "type-check"]
+lint-ruff = "ruff check ."
+lint-bandit = "bandit -c pyproject.toml -r src/tlaup"
+type-check = "mypy ."
+fix = ["format", "lint-fix"]
+format = "ruff format ."
+lint-fix = "ruff check --fix ."
+test = "pytest"
+install-hooks = "pre-commit install --install-hooks"
+audit = "detect-secrets audit .secrets.baseline"
+build = "uv build"
+clean = "rm -rf dist"
+
+twine-check = "twine check dist/*.whl dist/*.tar.gz"
+
+[tool.poe.tasks.check-release]
+sequence = [
+    "check",
+    "clean",
+    "build",
+    "twine-check",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = false
+exclude = ["build", "tests/"]
+
+# Per-module overrides for libraries without strict types
+[[tool.mypy.overrides]]
+module = "platformdirs.*"
+ignore_missing_imports = true

tlaup-0.8.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tlaup-0.8.2/src/tlaup/__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()

tlaup-0.8.2/src/tlaup/cache/github.py

@@ -0,0 +1,28 @@
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+from tlaup.ui import warn
+from tlaup.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}")

tlaup-0.8.2/src/tlaup/cli.py

@@ -0,0 +1,62 @@
+"""TLA+ CLI tool - entry point."""
+
+import importlib.metadata
+
+import typer
+
+from tlaup.cmd.check_java import check_java
+from tlaup.cmd.config import app as config_app
+from tlaup.cmd.fetch_cache import app as fetch_cache_app
+from tlaup.cmd.modules import app as modules_app
+from tlaup.cmd.tlc import tlc as run_tlc_cmd
+from tlaup.cmd.tools import app as tools_app
+from tlaup.config.loader import load_config
+from tlaup.versioning import get_app_version
+
+app = typer.Typer(
+    name="tlaup",
+    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("tlaup")
+        app_ver = get_app_version(base_version=meta["Version"])
+        typer.echo(f"{meta['Name']} v{app_ver}")
+        typer.echo(meta["Summary"])
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    _: bool = typer.Option(
+        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()

tlaup-0.8.2/src/tlaup/cmd/check_java.py

@@ -0,0 +1,19 @@
+import typer
+
+from tlaup.config.loader import load_config
+from tlaup.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

tlaup-0.8.2/src/tlaup/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

tlaup-0.8.2/src/tlaup/cmd/config/edit.py

@@ -0,0 +1,34 @@
+import os
+import shutil
+import subprocess
+
+import typer
+
+from tlaup.cmd.config import app
+from tlaup.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

tlaup-0.8.2/src/tlaup/cmd/config/list.py

@@ -0,0 +1,16 @@
+import typer
+
+from tlaup.cmd.config import app
+from tlaup.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())

tlaup-0.8.2/src/tlaup/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

tlaup-0.8.2/src/tlaup/cmd/fetch_cache/clear.py

@@ -0,0 +1,11 @@
+import typer
+
+from tlaup.cmd.fetch_cache import app
+from tlaup.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.")

tlaup-0.8.2/src/tlaup/cmd/modules/__init__.py

@@ -0,0 +1,16 @@
+import typer
+
+app = typer.Typer(name="modules", help="Manage TLA+ Java modules.", no_args_is_help=True)
+
+
+# Import functions for new commands
+from .add import add_module  # noqa: E402
+from .list import list_modules  # noqa: E402
+from .path import show_modules_path  # noqa: E402
+from .remove import remove_module  # noqa: E402
+
+# Register new commands with the typer app
+app.command(name="add")(add_module)
+app.command(name="list")(list_modules)
+app.command(name="remove")(remove_module)
+app.command(name="path")(show_modules_path)

tlaup-0.8.2/src/tlaup/cmd/modules/add.py

@@ -0,0 +1,140 @@
+import datetime
+import json
+import os
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+import typer
+
+from tlaup.config.loader import load_config
+from tlaup.java.classpath import ClasspathResolver, ResolveMode
+from tlaup.tlc.compiler import get_tlc_jar_path
+from tlaup.tlc.run_cache import clear_tlc_run_cache
+from tlaup.versioning.paths import get_modules_dir
+
+
+def find_override_classes(java_files: list[Path]) -> list[str]:
+    """Find all class names implementing ITLCOverrides in Java files."""
+    override_classes = []
+    package_pattern = re.compile(r"package\s+([a-zA-Z0-9_.]+)\s*;")
+    class_pattern = re.compile(
+        r"\bclass\s+([a-zA-Z0-9_]+)\b[^{]*\bimplements\b[^{]*\b(tlc2\.overrides\.)?ITLCOverrides\b"
+    )
+
+    for jf in java_files:
+        try:
+            content = jf.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+
+        # Strip comments to prevent false matches
+        content_no_comments = re.sub(r"//.*", "", content)
+        content_no_comments = re.sub(r"/\*.*?\*/", "", content_no_comments, flags=re.DOTALL)
+
+        package_match = package_pattern.search(content_no_comments)
+        package_name = package_match.group(1) if package_match else ""
+
+        for match in class_pattern.finditer(content_no_comments):
+            class_name = match.group(1)
+            full_class_name = f"{package_name}.{class_name}" if package_name else class_name
+            override_classes.append(full_class_name)
+
+    return override_classes
+
+
+def add_module(  # noqa: PLR0912, PLR0915
+    path: str = typer.Argument(..., help="Path to the module directory to add."),
+) -> None:
+    """Compile custom Java overrides and add/update the module in the cache."""
+    source_dir = Path(path).resolve()
+    if not source_dir.is_dir():
+        typer.echo(f"Error: Path does not exist or is not a directory: {source_dir}", err=True)
+        raise typer.Exit(1)
+
+    config = load_config()
+    module_name = source_dir.name
+    target_dir = get_modules_dir() / module_name
+
+    # Overwrite if exists
+    if target_dir.exists():
+        shutil.rmtree(target_dir)
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # 1. Copy directories (lib, modules, tlc2, and test/tests)
+    def copy_subfolder(subname: str) -> None:
+        src = source_dir / subname
+        if src.is_dir():
+            shutil.copytree(src, target_dir / subname)
+
+    typer.echo("Copying subfolders (lib, modules, test, tlc2)...")
+    copy_subfolder("lib")
+    copy_subfolder("modules")
+    copy_subfolder("tlc2")
+
+    if (source_dir / "test").is_dir():
+        copy_subfolder("test")
+    elif (source_dir / "tests").is_dir():
+        copy_subfolder("tests")
+
+    # 2. Compile Java overrides in cached version if tlc2/overrides exists
+    java_files = []
+    for candidate in [target_dir / "modules" / "tlc2" / "overrides", target_dir / "tlc2" / "overrides"]:
+        if candidate.is_dir():
+            java_files.extend(list(candidate.rglob("*.java")))
+
+    if java_files:
+        # Build classpath including tool_jar and local libs from the cached folder
+        cached_lib = target_dir / "lib"
+        extra_libs = []
+        if cached_lib.is_dir():
+            extra_libs.extend([str(j.absolute()) for j in cached_lib.glob("*.jar")])
+
+        tool_jar = get_tlc_jar_path()
+        if not tool_jar.exists():
+            typer.echo("Error: tla2tools.jar not found. Run 'tlaup tools install' first.", err=True)
+            shutil.rmtree(target_dir, ignore_errors=True)
+            raise typer.Exit(1)
+
+        resolver = ClasspathResolver(config, project_root=None, tool_jar=tool_jar, extra_libs=extra_libs)
+        classpath = os.pathsep.join(resolver.resolve(ResolveMode.COMPILE))
+
+        classes_dir = target_dir / "classes"
+        classes_dir.mkdir(parents=True, exist_ok=True)
+
+        cmd = ["javac", "-cp", classpath, "-d", str(classes_dir), *[str(f) for f in java_files]]
+        typer.echo("Compiling Java files in cached tlc2/overrides...")
+        try:
+            subprocess.run(cmd, check=True, capture_output=True, text=True)
+        except FileNotFoundError as err:
+            typer.echo("Error: 'javac' not found. Ensure JDK is installed.", err=True)
+            shutil.rmtree(target_dir, ignore_errors=True)
+            raise typer.Exit(1) from err
+        except subprocess.CalledProcessError as err:
+            typer.echo("Compilation failed!", err=True)
+            typer.echo(err.stdout, err=True)
+            typer.echo(err.stderr, err=True)
+            shutil.rmtree(target_dir, ignore_errors=True)
+            raise typer.Exit(1) from err
+
+        # Write service file
+        meta_inf = classes_dir / "META-INF" / "services"
+        meta_inf.mkdir(parents=True, exist_ok=True)
+        service_file = meta_inf / "tlc2.overrides.ITLCOverrides"
+
+        override_classes = find_override_classes(java_files)
+        if not override_classes:
+            override_classes = [config.tlc.overrides_class]
+
+        with service_file.open("w") as f:
+            for cls in override_classes:
+                f.write(f"{cls}\n")
+
+    # 3. Create metadata.json
+    metadata = {"name": module_name, "built_at": datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
+    with (target_dir / "metadata.json").open("w") as f:
+        json.dump(metadata, f, indent=2)
+
+    clear_tlc_run_cache()
+    typer.echo(f"Module '{module_name}' successfully added to cache.")