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

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

@@ -2,6 +2,38 @@
 
 ## 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`,
+  `build`, and `update`. New projects use the newest stable cataloged Mathlib
+  by default; `--core` opts out, while `--mathlib VERSION` selects a release.
+- Make `init` adopt an existing pinned Lake project without changing its graph,
+  or create a new project transactionally after its exact dependencies are
+  ready. `--plan`, `--offline`, `--max-download`, and `--seed-from` expose its
+  acquisition policy, and failed initialization leaves no partial project.
+- Add persistent discovery of exact local Lake graphs. `scan` registers existing
+  projects as zero-download seeds for future initialization and updates.
+- Preserve verified sparse-capsule build artifacts when materializing exact Git
+  sources for a mutable project, instead of throwing them away and forcing a
+  dependency rebuild.
+- Add explicit, transactional `update` to the newest cataloged Mathlib, with an
+  old/new revision and toolchain preview and rollback after failed adoption.
+- Include exact package revisions, Git tree hashes, and the shared workspace ID
+  in mutable-project check and build provenance.
+
 ## 2.5.0 - 2026-08-14
 
 - Make `lean-runtime init` create a concise `AGENTS.md` with build, checking,

{lean_runtime-2.5.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.5.0
+Version: 2.6.1
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0
@@ -181,31 +181,40 @@ project = lean.setup(project="./my-project")
 result = project.check_file("./my-project/MyProject/Main.lean")
 ```
 
-Create a normal Lake project whose exact dependencies are shared automatically:
+Create a normal Lake project. The newest stable cataloged Mathlib is the
+default, and exact dependencies are shared automatically:
 
 ```bash
-lean-runtime init MyProof --mathlib
+lean-runtime init MyProof
 cd MyProof
-lean-runtime build .
+lean-runtime check MyProof/Basic.lean
+lean-runtime build
 ```
 
 `init` also writes an `AGENTS.md` with the project build, checking, dependency,
 and shared-package rules for coding agents. Pass `--no-agents` to omit it; an
-existing `AGENTS.md` is never overwritten.
+existing `AGENTS.md` is never overwritten. Use `--core` for no Mathlib, or
+`--mathlib 4.33.0` to select a cataloged release. `lean-runtime update`
+explicitly moves a project to the newest cataloged Mathlib after a preview.
 
-Existing repositories can preview and adopt the same layout individually or in
-bulk:
+Running `lean-runtime init .` in an existing pinned Lake project adopts its
+current exact graph without running `lake update`. If you already have many
+Lake checkouts, register them once as local dependency seeds:
 
 ```bash
-lean-runtime attach ~/research --recursive
-lean-runtime attach ~/research --recursive --execute
+lean-runtime scan ~/research
+lean-runtime init .
 ```
 
-The dry run reports blockers and estimated recovery without changing anything.
-Adoption preserves each root `.lake/build`, verifies both the override and
-ordinary Lake views, then replaces only generated package copies with links to
-the content-addressed store. `lean-runtime detach . --execute` materializes an
-independent project again.
+`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.5.0 → lean_runtime-2.6.1}/README.md

@@ -145,31 +145,40 @@ project = lean.setup(project="./my-project")
 result = project.check_file("./my-project/MyProject/Main.lean")
 ```
 
-Create a normal Lake project whose exact dependencies are shared automatically:
+Create a normal Lake project. The newest stable cataloged Mathlib is the
+default, and exact dependencies are shared automatically:
 
 ```bash
-lean-runtime init MyProof --mathlib
+lean-runtime init MyProof
 cd MyProof
-lean-runtime build .
+lean-runtime check MyProof/Basic.lean
+lean-runtime build
 ```
 
 `init` also writes an `AGENTS.md` with the project build, checking, dependency,
 and shared-package rules for coding agents. Pass `--no-agents` to omit it; an
-existing `AGENTS.md` is never overwritten.
+existing `AGENTS.md` is never overwritten. Use `--core` for no Mathlib, or
+`--mathlib 4.33.0` to select a cataloged release. `lean-runtime update`
+explicitly moves a project to the newest cataloged Mathlib after a preview.
 
-Existing repositories can preview and adopt the same layout individually or in
-bulk:
+Running `lean-runtime init .` in an existing pinned Lake project adopts its
+current exact graph without running `lake update`. If you already have many
+Lake checkouts, register them once as local dependency seeds:
 
 ```bash
-lean-runtime attach ~/research --recursive
-lean-runtime attach ~/research --recursive --execute
+lean-runtime scan ~/research
+lean-runtime init .
 ```
 
-The dry run reports blockers and estimated recovery without changing anything.
-Adoption preserves each root `.lake/build`, verifies both the override and
-ordinary Lake views, then replaces only generated package copies with links to
-the content-addressed store. `lean-runtime detach . --execute` materializes an
-independent project again.
+`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.5.0 → lean_runtime-2.6.1}/docs/cli.md

@@ -146,30 +146,45 @@ environment can replay offline.
 ## Existing projects and core Lean
 
 ```bash
-lean-runtime check-file Main.lean --toolchain 4.32.2
-lean-runtime check-file ./existing-project/MyProject/Main.lean
-lean-runtime build ./existing-project MyLibrary
-lean-runtime init MyProof --mathlib
-lean-runtime init MyProof --mathlib --no-agents
+lean-runtime check Main.lean --toolchain 4.32.2
+lean-runtime check ./existing-project/MyProject/Main.lean
+lean-runtime build
+lean-runtime init MyProof
+lean-runtime init MyProof --core
+lean-runtime init --plan --max-download 500MiB
+lean-runtime update --plan
+lean-runtime scan ~/research
 lean-runtime attach ~/research --recursive
 lean-runtime attach ~/research --recursive --execute
 lean-runtime detach ./existing-project --execute
 lean-runtime install 4.32.2
 ```
 
-Without `--with`, the environment-aware `check` command requires an environment
-identifier. `check-file` is the direct local-project route. When no
+`check FILE` is the direct standalone/local-project route; the legacy
+`check ENVIRONMENT FILE` spelling remains accepted. When no
 `--project` or `--toolchain` is supplied, it discovers the nearest directory
 containing a Lake configuration and `lean-toolchain`, then passes the actual
 project-relative file to `lake env lean`.
 
-`init` creates a standard core or Mathlib Lake library and attaches its exact
-cataloged dependencies. `attach` is read-only unless `--execute` is present;
+`init` defaults to the newest stable cataloged Mathlib, or adopts an existing
+pinned Lake project without changing its graph. `--core` opts out of Mathlib.
+It prepares dependencies before atomically publishing a new project. `update`
+is the explicit transactional move to the newest cataloged Mathlib; `scan`
+records exact existing graphs as future local seeds. `attach` is read-only
+unless `--execute` is present;
 recursive mode inventories a project tree, reports blockers and estimated disk
 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.5.0 → lean_runtime-2.6.1}/docs/getting-started.md

@@ -18,33 +18,67 @@ Create a standard Lake library with the newest cataloged Mathlib release and
 shared exact dependencies:
 
 ```bash
-lean-runtime init MyProof --mathlib
+lean-runtime init MyProof
 cd MyProof
-lean-runtime build .
+lean-runtime check MyProof/Basic.lean
+lean-runtime build
 ```
 
 By default, `init` writes an `AGENTS.md` explaining the project workflow and
 shared-dependency safety rules to coding agents. Pass `--no-agents` to omit it.
 An existing file is preserved.
 
-Use `--mathlib 4.33.0` to select that release explicitly. Omit `--mathlib` for
-a core-only library. The root project remains an ordinary mutable Lake project;
+Use `--mathlib 4.33.0` to select that release explicitly, or `--core` for a
+core-only library. The root project remains an ordinary mutable Lake project;
 its dependency sources and build artifacts are reused by other projects with
 the same exact graph.
 
-For an existing project or a directory containing many projects, preview the
-migration before applying it:
+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 attach .
-lean-runtime attach ~/research --recursive
-lean-runtime attach ~/research --recursive --execute
+lean-runtime init . --name IntegralFramework
 ```
 
-The first two commands are read-only. Execution verifies the shared graph,
-replaces only generated package copies, and rolls back the swap if ordinary
-Lake cannot load the result. See [Local Lake projects](local-projects.md) for
-detachment, storage estimates, and the complete safety model.
+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 update --plan
+lean-runtime update
+```
+
+The update preview names both exact Mathlib revisions and toolchains. In a
+terminal, the second command asks for confirmation; use `--yes` in automation.
+
+For one existing pinned Lake project, preserve and adopt its current exact graph:
+
+```bash
+lean-runtime init .
+lean-runtime scan ~/research
+```
+
+`scan` only records exact local graphs as possible future zero-download seeds.
+Advanced bulk migration remains available through `attach`. See [Local Lake
+projects](local-projects.md) for detachment, storage estimates, and the complete
+safety model.
 
 ## Run a file
 

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

@@ -22,10 +22,10 @@ managed environment, dependency list, or explicit toolchain is supplied:
 result = Runtime().check_file("./my-project/MyProject/Main.lean")
 ```
 
-The CLI equivalent is:
+The primary CLI equivalent is:
 
 ```bash
-lean-runtime check-file ./my-project/MyProject/Main.lean
+lean-runtime check ./my-project/MyProject/Main.lean
 ```
 
 The actual project-relative file is passed to `lake env lean`, so imports of
@@ -43,19 +43,56 @@ Ordinary Lake workspaces put remote dependencies and their build artifacts in
 each repository's `.lake/packages`. New projects can start in shared mode:
 
 ```bash
-lean-runtime init MyProof --mathlib
+lean-runtime init MyProof
 cd MyProof
-lean-runtime build .
+lean-runtime check MyProof/Basic.lean
+lean-runtime build
 ```
 
 The generated files are a standard Lake project plus a small
 `lean-runtime.toml`. Root build outputs stay local; exact dependencies are
-shared. Select a cataloged release with `--mathlib 4.33.0`, or omit `--mathlib`
-for a core-only library. `init` also creates an `AGENTS.md` describing the safe
+shared. The newest stable cataloged Mathlib is selected by default. Select a
+release with `--mathlib 4.33.0`, or use `--core` for a core-only library.
+`init` also creates an `AGENTS.md` describing the safe
 build and dependency workflow unless `--no-agents` is passed; it never
 overwrites an existing guide.
 
-For one existing project, preview before changing anything:
+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
+downloads automatically.
+
+Move an adopted TOML project to the newest cataloged Mathlib explicitly:
+
+```bash
+lean-runtime update --plan
+lean-runtime update
+```
+
+The plan reports old and new release, commit, toolchain, local donor, and known
+download bytes. Acquisition happens before metadata changes, and failures
+restore the prior Lake files and attachment metadata.
+
+For advanced bulk onboarding, preview before changing anything:
 
 ```bash
 lean-runtime attach .

{lean_runtime-2.5.0 → lean_runtime-2.6.1}/lean_runtime/__init__.py

@@ -59,6 +59,9 @@ from .project_sharing import (
     AdoptionResult,
     DetachmentPlan,
     ProjectAdoption,
+    ProjectInitPlan,
+    ProjectScanResult,
+    ProjectUpdatePlan,
 )
 from .projects import (
     ProjectContext,
@@ -85,6 +88,9 @@ __all__ = [
     "AdoptionPlan",
     "AdoptionResult",
     "DetachmentPlan",
+    "ProjectInitPlan",
+    "ProjectScanResult",
+    "ProjectUpdatePlan",
     "EnvironmentComparison",
     "ComparisonEntry",
     "PortableCopyInfo",