lean-runtime 2.6.0__tar.gz → 2.6.1__tar.gz

{lean_runtime-2.6.0 → lean_runtime-2.6.1}/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 2.6.1 - 2026-08-14
+
+- Allow `lean-runtime init .` at an otherwise empty Git repository root while
+  preserving its original `.git` directory or worktree file, HEAD, and index.
+  Planning and execution now share target validation, so `init --plan` rejects
+  unsupported existing contents before reporting an acquisition-ready plan.
+- Add `init --name NAME` for repository directories whose filesystem spelling
+  should not determine the Lake package and Lean root module name. Repeating
+  the same named initialization is idempotent; a conflicting name is rejected.
+- Make `init --plan --offline` and `update --plan --offline` genuinely
+  network-free. Plans now report explicit blockers and return a failing status
+  when an exact local graph or required full toolchain is unavailable.
+
 ## 2.6.0 - 2026-08-14
 
 - Make the local-project path a four-command workflow: `init`, `check`,

{lean_runtime-2.6.0/lean_runtime.egg-info → lean_runtime-2.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 2.6.0
+Version: 2.6.1
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -209,6 +209,12 @@ lean-runtime init .
 `init --plan` is side-effect free; `--max-download 500MiB` and `--offline`
 enforce cold-start policy. Advanced bulk migration remains available through
 `attach`, and `detach --execute` materializes an independent project again.
+For a new project, the target may be absent, empty, or an otherwise empty Git
+repository root; existing Git identity and index state are preserved. A custom
+`AGENTS.md` is also allowed and retained. Other existing contents are rejected
+before acquisition rather than overwritten.
+When the directory spelling is not the intended Lean module capitalization,
+set it explicitly, for example `lean-runtime init . --name IntegralFramework`.
 
 One-shot helpers are available when setup reuse is unnecessary:
 

{lean_runtime-2.6.0 → lean_runtime-2.6.1}/README.md

@@ -173,6 +173,12 @@ lean-runtime init .
 `init --plan` is side-effect free; `--max-download 500MiB` and `--offline`
 enforce cold-start policy. Advanced bulk migration remains available through
 `attach`, and `detach --execute` materializes an independent project again.
+For a new project, the target may be absent, empty, or an otherwise empty Git
+repository root; existing Git identity and index state are preserved. A custom
+`AGENTS.md` is also allowed and retained. Other existing contents are rejected
+before acquisition rather than overwritten.
+When the directory spelling is not the intended Lean module capitalization,
+set it explicitly, for example `lean-runtime init . --name IntegralFramework`.
 
 One-shot helpers are available when setup reuse is unnecessary:
 

{lean_runtime-2.6.0 → lean_runtime-2.6.1}/docs/cli.md

@@ -177,6 +177,14 @@ recovery, and adopts each valid project transactionally. `detach` is likewise a
 preview unless `--execute` is present. Attached projects use shared mode by
 default in `lean-runtime build`; detach before requesting `--local`.
 
+A new `init` target may be absent, empty, or an otherwise empty Git root, with
+an optional existing `AGENTS.md`. Git metadata and the custom guide are
+preserved. Planning rejects any other existing contents using the same
+validation as execution.
+`--name NAME` overrides the inferred Lake package/root module name for a new
+project, which is useful when a lowercase repository name needs internal
+capitalization such as `IntegralFramework`.
+
 Add supporting source files with repeatable `--include` options:
 
 ```bash

{lean_runtime-2.6.0 → lean_runtime-2.6.1}/docs/getting-started.md

@@ -37,10 +37,27 @@ Before doing any work, `init --plan` reports the exact release, local reuse, and
 known download size. `--max-download 500MiB` refuses a larger transfer and
 `--offline` requires a matching local graph. Initialization is transactional:
 the target appears only after Lake and the shared dependency graph both verify.
+Offline plans perform no registry lookup; they return a blocked plan and a
+nonzero status when the required exact local graph is absent.
 Project development requires one full Lake-capable Lean toolchain per Lean
 version. When it is absent, the plan says its Elan download size is unknown;
 `--offline` and `--max-download` fail closed instead of silently installing it.
 
+The target may be a missing directory, an empty directory, or an otherwise
+empty Git repository root. In the Git case, `init` preserves the existing HEAD,
+index, remotes, and worktree metadata. It also preserves an existing
+`AGENTS.md`; any other non-project contents are rejected by both `--plan` and
+execution rather than overwritten.
+The directory name normally supplies the Lake package/root module name. Override
+it when capitalization matters, for example:
+
+```bash
+lean-runtime init . --name IntegralFramework
+```
+
+The same command can be rerun safely after initialization; a different name is
+rejected rather than silently renaming an existing project.
+
 Dependency upgrades are explicit:
 
 ```bash

{lean_runtime-2.6.0 → lean_runtime-2.6.1}/docs/local-projects.md

@@ -61,11 +61,21 @@ Initialization acquires and verifies the exact graph before publishing the
 target directory. Use `--plan` for a side-effect-free cost report, `--offline`
 to require local data, `--max-download SIZE` to enforce a transfer ceiling, or
 `--seed-from PROJECT` to name an exact local donor.
+Offline planning never queries configured registries. A missing exact local
+graph appears as a blocker and makes the planning command fail.
 The plan separately reports whether the full Lake-capable toolchain is already
 installed. Because Elan does not publish a preflight byte count, a missing full
 toolchain is rejected under `--offline` or `--max-download` rather than silently
 bypassing the policy.
 
+An otherwise empty Git root is a valid new-project target. The original `.git`
+directory—or `.git` worktree file—is transferred through the atomic publication
+without changing HEAD, the index, or remotes. A pre-existing `AGENTS.md` is also
+preserved. Other contents must be moved first or represented by an existing
+pinned Lake project; the read-only plan enforces the same rule as execution.
+Use `--name NAME` when creating inside a lowercase or otherwise differently
+named repository and the Lean root module needs an explicit spelling.
+
 For an existing pinned project, `lean-runtime init .` adopts its current
 manifest without changing versions. Register a collection once with
 `lean-runtime scan ~/research`; future exact matches are preferred over

{lean_runtime-2.6.0 → lean_runtime-2.6.1}/lean_runtime/cli.py

@@ -12,7 +12,7 @@ from typing import Any
 
 from .console import styler_for
 from .environments import ExecutionCapture
-from .errors import LeanRuntimeError, MaterializationError, ResolutionError
+from .errors import LeanRuntimeError, MaterializationError, ProjectError, ResolutionError
 from .events import RuntimeEvent
 from .lake import ROOT_MODULE
 from .lockfiles import EnvironmentLock
@@ -184,7 +184,8 @@ def _render_init_plan(plan: ProjectInitPlan) -> None:
         print(f"Exact dependencies: {len(plan.packages)} package(s); versions unchanged")
         return
     context = f"Mathlib {plan.mathlib_version}" if plan.mathlib_version else "core Lean"
-    print(f"Create {plan.root.name} · {context} · {plan.toolchain}")
+    name = plan.project_name or plan.root.name
+    print(f"Create {name} in {plan.root} · {context} · {plan.toolchain}")
     if not plan.toolchain_installed:
         print("Full Lake toolchain: download required (size not published by Elan)")
     if plan.seed_root is not None:
@@ -194,6 +195,8 @@ def _render_init_plan(plan: ProjectInitPlan) -> None:
         print(f"Download: {format_byte_size(plan.download_bytes)}")
     else:
         print("Download: unknown (no compatible published artifact could be priced)")
+    for blocker in plan.blockers:
+        print(f"Blocker: {blocker}")
 
 
 def _render_update_plan(plan: ProjectUpdatePlan) -> None:
@@ -538,6 +541,7 @@ def parser() -> argparse.ArgumentParser:
         "init", help="create a latest-Mathlib project or adopt an existing Lake project"
     )
     init.add_argument("path", type=Path, nargs="?", default=Path("."))
+    init.add_argument("--name", help="explicit Lake package and root module name")
     init_context = init.add_mutually_exclusive_group()
     init_context.add_argument(
         "--mathlib",
@@ -666,6 +670,7 @@ def main(argv: list[str] | None = None) -> int:
         if args.command == "init":
             init_plan = runtime.plan_project_init(
                 args.path,
+                name=args.name,
                 mathlib=args.mathlib,
                 toolchain=args.toolchain,
                 seed_from=args.seed_from,
@@ -675,11 +680,16 @@ def main(argv: list[str] | None = None) -> int:
                     _json(init_plan.to_dict())
                 else:
                     _render_init_plan(init_plan)
-                return 0
+                return 0 if init_plan.ready else 1
+            if not init_plan.ready:
+                raise ProjectError(
+                    "project cannot be initialized:\n- " + "\n- ".join(init_plan.blockers)
+                )
             if not args.json:
                 _render_init_plan(init_plan)
             init_result = runtime.init_project(
                 args.path,
+                name=args.name,
                 mathlib=args.mathlib,
                 toolchain=args.toolchain,
                 agents=args.agents,

{lean_runtime-2.6.0 → lean_runtime-2.6.1}/lean_runtime/project_sharing.py

@@ -232,6 +232,12 @@ class ProjectInitPlan:
     download_bytes_complete: bool
     already_attached: bool = False
     toolchain_installed: bool = False
+    project_name: str | None = None
+    blockers: tuple[str, ...] = ()
+
+    @property
+    def ready(self) -> bool:
+        return not self.blockers
 
     def to_dict(self) -> dict[str, Any]:
         return {
@@ -245,6 +251,9 @@ class ProjectInitPlan:
             "download_bytes_complete": self.download_bytes_complete,
             "already_attached": self.already_attached,
             "toolchain_installed": self.toolchain_installed,
+            "project_name": self.project_name,
+            "ready": self.ready,
+            "blockers": list(self.blockers),
         }
 
 

{lean_runtime-2.6.0 → lean_runtime-2.6.1}/lean_runtime/runtime.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import os
 import subprocess
+import sys
 import tempfile
 import threading
 from collections.abc import Mapping, Sequence
@@ -14,6 +15,11 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - exercised by the Python 3.10 CI job
+    import tomli as tomllib
+
 from ._paths import remove_tree
 from .backends import Backend, LocalBackend
 from .bundles import EnvironmentBundles, PortableCopyInfo
@@ -1302,6 +1308,18 @@ class Runtime:
             )
         self.toolchains.ensure(toolchain)
 
+    def _project_toolchain_blockers(self, toolchain: str, *, installed: bool) -> tuple[str, ...]:
+        if installed:
+            return ()
+        if self.availability == "local":
+            return (f"offline setup requires the full {toolchain} toolchain locally",)
+        if self.max_download_bytes is not None:
+            return (
+                "the full Lake-capable Lean toolchain is missing and its Elan download "
+                "cannot be preflighted under --max-download",
+            )
+        return ()
+
     def plan_project_update(
         self,
         path: str | os.PathLike[str] = ".",
@@ -1370,16 +1388,24 @@ class Runtime:
         download_bytes: int | None = 0
         complete = True
         if changed:
+            blockers.extend(
+                self._project_toolchain_blockers(latest.toolchain, installed=toolchain_installed)
+            )
             seeds, seed_root = self._project_seed_paths(
                 latest.toolchain,
                 latest_packages,
                 seed_from=Path(seed_from) if seed_from is not None else None,
             )
             if not seeds:
-                acquisition = self.plan_exact(latest.lock, import_roots=("Mathlib",))
-                raw_download = acquisition.get("download_bytes")
-                download_bytes = raw_download if isinstance(raw_download, int) else None
-                complete = acquisition.get("download_bytes_complete") is True
+                if self.availability == "local":
+                    download_bytes = None
+                    complete = False
+                    blockers.append("offline update has no exact local Mathlib dependency graph")
+                else:
+                    acquisition = self.plan_exact(latest.lock, import_roots=("Mathlib",))
+                    raw_download = acquisition.get("download_bytes")
+                    download_bytes = raw_download if isinstance(raw_download, int) else None
+                    complete = acquisition.get("download_bytes_complete") is True
         if not toolchain_installed:
             download_bytes = None
             complete = False
@@ -1564,10 +1590,29 @@ class Runtime:
             return registered, root
         return {}, None
 
+    @staticmethod
+    def _validate_new_project_target(target: Path) -> tuple[Path, ...]:
+        """Validate metadata that can be preserved around an atomic project init."""
+        if not target.exists():
+            return ()
+        if not target.is_dir():
+            raise ProjectError(f"initialization target is not a directory: {target}")
+        entries = tuple(target.iterdir())
+        allowed = {".git", "AGENTS.md"}
+        unsupported = [entry for entry in entries if entry.name not in allowed]
+        if unsupported:
+            names = ", ".join(sorted(entry.name for entry in unsupported))
+            raise ProjectError(
+                f"initialization target is not empty: {target} ({names}); choose an empty "
+                "directory or run `lean-runtime init .` inside an existing Lake project"
+            )
+        return entries
+
     def plan_project_init(
         self,
         path: str | os.PathLike[str] = ".",
         *,
+        name: str | None = None,
         mathlib: str | None = "latest",
         toolchain: str | None = None,
         seed_from: str | os.PathLike[str] | None = None,
@@ -1575,12 +1620,30 @@ class Runtime:
         """Plan project creation or adoption without changing the target."""
         target = Path(path).expanduser().resolve()
         if (target / "lakefile.toml").is_file() or (target / "lakefile.lean").is_file():
+            if name is not None:
+                lakefile = target / "lakefile.toml"
+                if not lakefile.is_file():
+                    raise ProjectError(
+                        "cannot verify --name for an existing lakefile.lean project; omit it"
+                    )
+                try:
+                    with lakefile.open("rb") as stream:
+                        configured_name = tomllib.load(stream).get("name")
+                except (OSError, tomllib.TOMLDecodeError) as exc:
+                    raise ProjectError(f"could not verify existing project --name: {exc}") from exc
+                if configured_name != name:
+                    raise ProjectError(
+                        f"existing project is named {configured_name!r}, not {name!r}"
+                    )
             adoption = self.plan_project_adoption(target).projects[0]
             installed = (
                 self._toolchain_installed(adoption.toolchain)
                 if adoption.toolchain is not None
                 else False
             )
+            blockers = tuple(adoption.blockers) + self._project_toolchain_blockers(
+                adoption.toolchain or "unknown", installed=installed
+            )
             return ProjectInitPlan(
                 target,
                 "adopt",
@@ -1592,7 +1655,17 @@ class Runtime:
                 True,
                 adoption.attached,
                 installed,
+                None,
+                blockers,
             )
+        self._validate_new_project_target(target)
+        project_name = name or target.name
+        if name is not None and (
+            not name
+            or not (name[0].isalpha() or name[0] == "_")
+            or any(not (character.isalnum() or character == "_") for character in name)
+        ):
+            raise ProjectError("project --name must be a Lean identifier")
         selected = self._mathlib_catalog_entry(mathlib or "latest")
         selected_toolchain = normalize_toolchain(toolchain or selected.toolchain)
         if mathlib is not None and selected_toolchain != selected.toolchain:
@@ -1602,6 +1675,7 @@ class Runtime:
             )
         if mathlib is None:
             installed = self._toolchain_installed(selected_toolchain)
+            blockers = self._project_toolchain_blockers(selected_toolchain, installed=installed)
             return ProjectInitPlan(
                 target,
                 "create",
@@ -1613,6 +1687,8 @@ class Runtime:
                 installed,
                 False,
                 installed,
+                project_name,
+                blockers,
             )
         selected_packages = selected.lock.manifest["packages"]
         assert isinstance(selected_packages, list)
@@ -1621,15 +1697,25 @@ class Runtime:
             selected_packages,
             seed_from=Path(seed_from) if seed_from is not None else None,
         )
+        toolchain_installed = self._toolchain_installed(selected_toolchain)
+        init_blockers = list(
+            self._project_toolchain_blockers(
+                selected_toolchain,
+                installed=toolchain_installed,
+            )
+        )
         if seed_paths:
             download_bytes: int | None = 0
             complete = True
+        elif self.availability == "local":
+            download_bytes = None
+            complete = False
+            init_blockers.append("offline setup has no exact local Mathlib dependency graph")
         else:
             acquisition = self.plan_exact(selected.lock, import_roots=("Mathlib",))
             raw_download = acquisition.get("download_bytes")
             download_bytes = raw_download if isinstance(raw_download, int) else None
             complete = acquisition.get("download_bytes_complete") is True
-        toolchain_installed = self._toolchain_installed(selected_toolchain)
         if not toolchain_installed:
             download_bytes = None
             complete = False
@@ -1644,12 +1730,15 @@ class Runtime:
             complete,
             False,
             toolchain_installed,
+            project_name,
+            tuple(init_blockers),
         )
 
     def init_project(
         self,
         path: str | os.PathLike[str] = ".",
         *,
+        name: str | None = None,
         mathlib: str | None = "latest",
         toolchain: str | None = None,
         agents: bool = True,
@@ -1670,6 +1759,7 @@ class Runtime:
 
         plan = self.plan_project_init(
             target,
+            name=name,
             mathlib=mathlib,
             toolchain=toolchain,
             seed_from=seed_from,
@@ -1697,18 +1787,14 @@ class Runtime:
                 seed_packages = environment.workspace / str(raw_packages)
                 seed_package_paths = None
         target.parent.mkdir(parents=True, exist_ok=True)
-        existing_entries = tuple(target.iterdir()) if target.is_dir() else ()
-        unsupported = [entry for entry in existing_entries if entry.name != "AGENTS.md"]
-        if unsupported:
-            raise ProjectError(
-                f"initialization target is not empty: {target}; use `lean-runtime init .` "
-                "inside an existing Lake project to adopt it"
-            )
+        existing_entries = self._validate_new_project_target(target)
         staging = Path(
             tempfile.mkdtemp(prefix=f".{target.name}.lean-runtime-init-", dir=target.parent)
         )
         backup: Path | None = None
         published = False
+        original_git = next((entry for entry in existing_entries if entry.name == ".git"), None)
+        git_transferred = False
         try:
             custom_agents = target / "AGENTS.md"
             if custom_agents.is_file():
@@ -1719,7 +1805,7 @@ class Runtime:
                 "--offline",
                 f"--dir={staging}",
                 "init",
-                target.name,
+                plan.project_name or target.name,
                 "lib",
             )
             process = subprocess.run(
@@ -1798,6 +1884,14 @@ class Runtime:
             agents_file = staging / "AGENTS.md"
             if agents and not agents_file.exists():
                 agents_file.write_text(_DEFAULT_AGENTS_GUIDE, encoding="utf-8")
+            if original_git is not None:
+                generated_git = staging / ".git"
+                if generated_git.is_dir() and not generated_git.is_symlink():
+                    remove_tree(generated_git)
+                elif generated_git.exists() or generated_git.is_symlink():
+                    generated_git.unlink()
+                original_git.replace(generated_git)
+                git_transferred = True
             if target.exists():
                 backup = target.parent / f".{target.name}.lean-runtime-backup-{os.getpid()}"
                 target.replace(backup)
@@ -1812,6 +1906,13 @@ class Runtime:
                 self.shared_projects.remember_project(context)
             return replace(result.results[0], root=target)
         except BaseException:
+            if git_transferred:
+                staged_git = (target if published else staging) / ".git"
+                restore_root = backup if backup is not None and backup.exists() else target
+                if staged_git.exists() or staged_git.is_symlink():
+                    restore_root.mkdir(parents=True, exist_ok=True)
+                    staged_git.replace(restore_root / ".git")
+                git_transferred = False
             if published:
                 if target.exists():
                     remove_tree(target)

{lean_runtime-2.6.0 → lean_runtime-2.6.1/lean_runtime.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 2.6.0
+Version: 2.6.1
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -209,6 +209,12 @@ lean-runtime init .
 `init --plan` is side-effect free; `--max-download 500MiB` and `--offline`
 enforce cold-start policy. Advanced bulk migration remains available through
 `attach`, and `detach --execute` materializes an independent project again.
+For a new project, the target may be absent, empty, or an otherwise empty Git
+repository root; existing Git identity and index state are preserved. A custom
+`AGENTS.md` is also allowed and retained. Other existing contents are rejected
+before acquisition rather than overwritten.
+When the directory spelling is not the intended Lean module capitalization,
+set it explicitly, for example `lean-runtime init . --name IntegralFramework`.
 
 One-shot helpers are available when setup reuse is unnecessary:
 

{lean_runtime-2.6.0 → lean_runtime-2.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lean-runtime"
-version = "2.6.0"
+version = "2.6.1"
 description = "Run Lean 4 proofs from Python or standalone files"
 readme = "README.md"
 requires-python = ">=3.10"

{lean_runtime-2.6.0 → lean_runtime-2.6.1}/tests/test_cli.py

@@ -44,6 +44,7 @@ def test_project_sharing_commands_have_safe_defaults() -> None:
     assert init.mathlib == "4.33.0"
     assert init.agents
     assert parser().parse_args(["init", "demo", "--core"]).mathlib is None
+    assert parser().parse_args(["init", ".", "--name", "DemoProject"]).name == "DemoProject"
     assert not parser().parse_args(["init", "demo", "--no-agents"]).agents
     attach = parser().parse_args(["attach", "projects", "--recursive"])
     assert attach.recursive and not attach.execute

{lean_runtime-2.6.0 → lean_runtime-2.6.1}/tests/test_programs.py

@@ -18,7 +18,7 @@ def _payload(root: Path) -> Path:
     payload = root / "payload"
     payload.mkdir()
     executable = payload / "echo-bridge"
-    executable.write_text("#!/bin/sh\nwhile IFS= read -r line; do printf '%s\\n' \"$line\"; done\n")
+    executable.write_text("#!/bin/sh\nexec /bin/cat\n")
     executable.chmod(0o755)
     return payload