worktree-runtime 0.1.0a3__tar.gz → 0.1.0a4__tar.gz

{worktree_runtime-0.1.0a3 → worktree_runtime-0.1.0a4}/Cargo.lock

@@ -1,6 +1,6 @@
 # This file is automatically @generated by Cargo.
 # It is not intended for manual editing.
-version = 3
+version = 4
 
 [[package]]
 name = "android_system_properties"
@@ -743,7 +743,7 @@ dependencies = [
 
 [[package]]
 name = "worktree_runtime_core"
-version = "0.1.0-alpha.3"
+version = "0.1.0-alpha.4"
 dependencies = [
  "chrono",
  "fs2",
@@ -760,7 +760,7 @@ dependencies = [
 
 [[package]]
 name = "worktree_runtime_pyo3"
-version = "0.1.0-alpha.3"
+version = "0.1.0-alpha.4"
 dependencies = [
  "chrono",
  "pyo3",

{worktree_runtime-0.1.0a3 → worktree_runtime-0.1.0a4}/Cargo.toml

@@ -3,9 +3,9 @@ resolver = "2"
 members = ["crates/worktree_runtime_core", "crates/worktree_runtime_pyo3"]
 
 [workspace.package]
-version = "0.1.0-alpha.3"
+version = "0.1.0-alpha.4"
 edition = "2021"
-rust-version = "1.75"
+rust-version = "1.85"
 license = "LicenseRef-Proprietary"
 publish = false
 
@@ -18,7 +18,7 @@ sha1 = "0.10"
 fs2 = "0.4"
 tempfile = "3.10"
 wait-timeout = "0.2"
-pyo3 = { version = "0.29", features = ["extension-module"] }
+pyo3 = { version = "0.29", features = ["extension-module", "abi3-py310"] }
 chrono = "0.4"
 
 [profile.release]

{worktree_runtime-0.1.0a3 → worktree_runtime-0.1.0a4}/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2026 adaptive-task contributors
+Copyright (c) 2026 bamboocity
 All rights reserved.
 
 This software and associated documentation files (the "Software") are
@@ -6,6 +6,12 @@ proprietary. Unauthorized copying, modification, distribution, or use of
 the Software, via any medium, is strictly prohibited except as expressly
 authorized in writing by the copyright holder.
 
+The Software is distributed on the Python Package Index as binary wheels
+and as a source distribution (sdist) that contains this source code. That
+distribution is provided solely so the package can be installed and built;
+it does not grant any right to copy, modify, or redistribute the source
+beyond what is necessary to install 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

worktree_runtime-0.1.0a4/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: worktree-runtime
+Version: 0.1.0a4
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Rust
+Classifier: Typing :: Typed
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pyyaml>=6.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.14 ; extra == 'dev'
+Provides-Extra: dev
+License-File: LICENSE
+Summary: Worktree identity, binding persistence, and checkout substrate
+Author: bamboocity
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/bamboocity/worktree-runtime/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/bamboocity/worktree-runtime
+
+# worktree-runtime
+
+Library for worktree **identity**, **binding persistence**, **checkout
+validation**, and **path resolution**.
+
+Consumers (adaptive-task / Noveler) call this so they do not each invent
+project id, session↔worktree binding, main-vs-linked checks, or
+state / shared paths. The public symbol list is
+[`src/worktree_runtime/SURFACE.yaml`](src/worktree_runtime/SURFACE.yaml).
+
+Binding store API: `register_binding`, `load_binding`, `recover_binding`,
+`list_bindings`, and `remove_binding`. `git worktree remove` and vanish stay
+in the consumer.
+
+Rust is the implementation SSOT. Python is a shim, typing stubs, contract tests,
+and a thin audit CLI. Missing native support is an install error; there is no
+silent Python fallback in this project.
+
+## Scope
+
+This crate answers four questions and records consumer mutations:
+
+| Responsibility | What the library does |
+| --- | --- |
+| Identity | Resolve project id, main branches, GitHub policy, and the `NOVELER_*` / location env catalog from cwd, env, git, and project config. |
+| Binding | Persist, load, recover, and validate a session↔worktree record (`WorktreeBinding`). Reject before treating a cwd as bound. |
+| Checkout | Resolve a `GitWorktree` (`rev-parse`), classify main vs linked, list porcelain entries, emit reason codes. |
+| Path | Resolve worktree base / dir / state dir / known bases with fixed precedence. `NOVELER_WORKTREE_BASE` and `config/worktree.yaml` overrides apply only when `CI` / `GITHUB_ACTIONS` is set; elsewhere the base is `~/.adaptive-task/worktrees/<project_id>`. Normalize and fingerprint paths. |
+
+Audit (`record_event` / `read_records` / rotation, plus
+`presentation/audit_cli.py`) is append-only logging of consumer git
+mutations (`worktree_remove`, `branch_delete`). It is not a session log.
+
+### Out of scope
+
+- **Agent isolation.** Codex Desktop, Cursor, and Claude Code create a
+  worktree (or checkout) so one chat does not dirty the user's main tree.
+  That sandbox is a different layer. This package does not replace it.
+- **Session orchestration.** `adaptive-task init` / `next` / `report` stay
+  in the consumer.
+- **Prep / vanish / cleanup hooks.** Detecting a disappeared worktree,
+  refusing cleanup, and running merge-cleanup tooling stay in adaptive-task.
+- **`git worktree add` / `remove` as a product operation.** This crate
+  resolves locations and validates state. The consumer mutates git.
+
+Using Codex Desktop only as an editor does not require importing this
+package. Running adaptive-task identity, binding, or path policy still does.
+Agent isolation worktrees and session worktrees can nest. Config may move
+the session base when `CODEX_CLI` or `CLAUDE_CODE` is set. That override
+exists because the two layers meet; it does not make this library redundant.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    callers["consumers"] -->|"worktree_runtime.api"| shim["Python shim and stubs"]
+    shim --> pyo3["PyO3 binding"]
+    pyo3 --> core["Rust core"]
+    contract["contract pytest"] -->|"black-box"| shim
+    cargo["cargo test"] --> core
+    release["maturin wheels"] --> callers
+```
+
+## Layout
+
+Layout rationale is in [DESIGN.md](DESIGN.md).
+
+- `crates/worktree_runtime_core/` — behavior SSOT
+- `crates/worktree_runtime_pyo3/` — Python C-API translation only
+- `src/worktree_runtime/` — `api` re-export, `.pyi`, `SURFACE.yaml`, `presentation/audit_cli.py`
+- `src/_worktree_runtime_rust/` — placeholder package that hosts the cdylib built by maturin (`python-source = "src"`)
+- `tests/contract/` — `from worktree_runtime.api import ...` only; `tests/cli/` — audit CLI exit codes
+
+Distribution name is `worktree-runtime`. Import name is `worktree_runtime`.
+`pyproject.toml` version and `Cargo.toml` `workspace.package.version` must match.
+The crate is proprietary (`LICENSE`; all rights reserved). CI uses the `stable` toolchain with rustfmt and clippy.
+
+## Change protocol
+
+Multi-file, refactor, behavior, or core+pyo3+facade+contract work: run
+`adaptive-gate` first ([AGENTS.md](AGENTS.md) Routing). Testing policy:
+`.cursor/rules/testing.mdc`.
+
+1. Behavior: add a failing cargo execution test, then implement in
+   `worktree_runtime_core` and run `cargo test`.
+2. Public-surface shape only: update `SURFACE.yaml` and `.pyi`, plus a thin
+   contract assertion under `tests/contract/`. Do not put behavior suites in
+   pytest.
+3. Export through PyO3; keep the shim as a re-export.
+4. When the public surface changed, build a wheel and run the contract and
+   CLI pytest. `cargo fmt --check` and `clippy -D warnings` are required.
+
+The verify loop (commands, hook setup, release steps) is defined once in
+[BUILD.md](BUILD.md).
+
+## Build
+
+See [BUILD.md](BUILD.md). CI always runs fmt, clippy, cargo test, maturin,
+contract+CLI pytest, `mypy.stubtest`, and an MSRV check, through
+`.github/actions/rust-checks`.
+Wheels are `abi3-py310` (CPython 3.10+) for Windows amd64, macOS x86_64 and
+arm64, and manylinux x86_64 / aarch64. Pure-Python wheels are not published.
+

worktree_runtime-0.1.0a4/README.md

@@ -0,0 +1,102 @@
+# worktree-runtime
+
+Library for worktree **identity**, **binding persistence**, **checkout
+validation**, and **path resolution**.
+
+Consumers (adaptive-task / Noveler) call this so they do not each invent
+project id, session↔worktree binding, main-vs-linked checks, or
+state / shared paths. The public symbol list is
+[`src/worktree_runtime/SURFACE.yaml`](src/worktree_runtime/SURFACE.yaml).
+
+Binding store API: `register_binding`, `load_binding`, `recover_binding`,
+`list_bindings`, and `remove_binding`. `git worktree remove` and vanish stay
+in the consumer.
+
+Rust is the implementation SSOT. Python is a shim, typing stubs, contract tests,
+and a thin audit CLI. Missing native support is an install error; there is no
+silent Python fallback in this project.
+
+## Scope
+
+This crate answers four questions and records consumer mutations:
+
+| Responsibility | What the library does |
+| --- | --- |
+| Identity | Resolve project id, main branches, GitHub policy, and the `NOVELER_*` / location env catalog from cwd, env, git, and project config. |
+| Binding | Persist, load, recover, and validate a session↔worktree record (`WorktreeBinding`). Reject before treating a cwd as bound. |
+| Checkout | Resolve a `GitWorktree` (`rev-parse`), classify main vs linked, list porcelain entries, emit reason codes. |
+| Path | Resolve worktree base / dir / state dir / known bases with fixed precedence. `NOVELER_WORKTREE_BASE` and `config/worktree.yaml` overrides apply only when `CI` / `GITHUB_ACTIONS` is set; elsewhere the base is `~/.adaptive-task/worktrees/<project_id>`. Normalize and fingerprint paths. |
+
+Audit (`record_event` / `read_records` / rotation, plus
+`presentation/audit_cli.py`) is append-only logging of consumer git
+mutations (`worktree_remove`, `branch_delete`). It is not a session log.
+
+### Out of scope
+
+- **Agent isolation.** Codex Desktop, Cursor, and Claude Code create a
+  worktree (or checkout) so one chat does not dirty the user's main tree.
+  That sandbox is a different layer. This package does not replace it.
+- **Session orchestration.** `adaptive-task init` / `next` / `report` stay
+  in the consumer.
+- **Prep / vanish / cleanup hooks.** Detecting a disappeared worktree,
+  refusing cleanup, and running merge-cleanup tooling stay in adaptive-task.
+- **`git worktree add` / `remove` as a product operation.** This crate
+  resolves locations and validates state. The consumer mutates git.
+
+Using Codex Desktop only as an editor does not require importing this
+package. Running adaptive-task identity, binding, or path policy still does.
+Agent isolation worktrees and session worktrees can nest. Config may move
+the session base when `CODEX_CLI` or `CLAUDE_CODE` is set. That override
+exists because the two layers meet; it does not make this library redundant.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    callers["consumers"] -->|"worktree_runtime.api"| shim["Python shim and stubs"]
+    shim --> pyo3["PyO3 binding"]
+    pyo3 --> core["Rust core"]
+    contract["contract pytest"] -->|"black-box"| shim
+    cargo["cargo test"] --> core
+    release["maturin wheels"] --> callers
+```
+
+## Layout
+
+Layout rationale is in [DESIGN.md](DESIGN.md).
+
+- `crates/worktree_runtime_core/` — behavior SSOT
+- `crates/worktree_runtime_pyo3/` — Python C-API translation only
+- `src/worktree_runtime/` — `api` re-export, `.pyi`, `SURFACE.yaml`, `presentation/audit_cli.py`
+- `src/_worktree_runtime_rust/` — placeholder package that hosts the cdylib built by maturin (`python-source = "src"`)
+- `tests/contract/` — `from worktree_runtime.api import ...` only; `tests/cli/` — audit CLI exit codes
+
+Distribution name is `worktree-runtime`. Import name is `worktree_runtime`.
+`pyproject.toml` version and `Cargo.toml` `workspace.package.version` must match.
+The crate is proprietary (`LICENSE`; all rights reserved). CI uses the `stable` toolchain with rustfmt and clippy.
+
+## Change protocol
+
+Multi-file, refactor, behavior, or core+pyo3+facade+contract work: run
+`adaptive-gate` first ([AGENTS.md](AGENTS.md) Routing). Testing policy:
+`.cursor/rules/testing.mdc`.
+
+1. Behavior: add a failing cargo execution test, then implement in
+   `worktree_runtime_core` and run `cargo test`.
+2. Public-surface shape only: update `SURFACE.yaml` and `.pyi`, plus a thin
+   contract assertion under `tests/contract/`. Do not put behavior suites in
+   pytest.
+3. Export through PyO3; keep the shim as a re-export.
+4. When the public surface changed, build a wheel and run the contract and
+   CLI pytest. `cargo fmt --check` and `clippy -D warnings` are required.
+
+The verify loop (commands, hook setup, release steps) is defined once in
+[BUILD.md](BUILD.md).
+
+## Build
+
+See [BUILD.md](BUILD.md). CI always runs fmt, clippy, cargo test, maturin,
+contract+CLI pytest, `mypy.stubtest`, and an MSRV check, through
+`.github/actions/rust-checks`.
+Wheels are `abi3-py310` (CPython 3.10+) for Windows amd64, macOS x86_64 and
+arm64, and manylinux x86_64 / aarch64. Pure-Python wheels are not published.

worktree_runtime-0.1.0a4/crates/worktree_runtime_core/AGENTS.md

@@ -0,0 +1,50 @@
+# worktree_runtime_core
+
+This crate is the behavior SSOT. Do not add PyO3 or Python dependencies.
+Behavior changes belong here with `cargo test` (`.cursor/rules/testing.mdc`);
+do not treat pytest as the SSOT.
+
+## Layers
+
+- `domain/` — value objects and pure rules (`binding`, `audit`, `paths`,
+  `porcelain`, `git_worktree`, `github_policy`). Today `paths::normalize_path`
+  still canonicalizes through the filesystem and `WorktreeBinding::new` calls
+  it; treat that as a known exception, do not add more I/O to `domain/`.
+- `application/` — services that compose domain + infrastructure
+  (`binding_lifecycle`, `validation`, `git_worktree_service`). They own the
+  reason codes callers branch on.
+- `infrastructure/` — filesystem, env, git subprocess, config readers.
+
+## Conventions that are not obvious from the code
+
+- **git**: every subprocess goes through `infrastructure::git_adapter`.
+  `git_output` returns `Result<String, GitInvokeError>`; `Exit` means the
+  repository state is unusable (not a repo, detached HEAD), every other
+  variant means git itself could not run and callers report
+  `WORKTREE_GIT_UNAVAILABLE`. Do not collapse errors to `""`. Tests
+  simulate a missing binary with `common::MissingGit` (thread-local
+  `override_git_program`), never by clearing `PATH`.
+- **Reason codes** are a public contract (adaptive-task branches on them).
+  Adding one needs a CHANGELOG entry; renaming one is a breaking change.
+- **Binding store** (`infrastructure::binding_store`) is locked
+  (`bindings.json.lock`) and fail-closed: a corrupt file is an error, never
+  an empty store.
+- **Audit** (`infrastructure::audit_*`) is fail-open by design: a failed
+  write prints `[WORKTREE-AUDIT-FAILOPEN] ...` to stderr and returns
+  `Err(AuditWriteError)`; the PyO3 layer decides whether to raise
+  (`strict`). Rotation runs under the append lock; `read_records` reads
+  archives too. The only `unsafe` in the crate is `libc::gethostname` in
+  `audit_writer.rs` (unix).
+- **Config precedence**: `NOVELER_WORKTREE_BASE` and
+  `config/worktree.yaml` overrides are honored only when `CI` or
+  `GITHUB_ACTIONS` is set (`worktree_base_resolver.rs`). Outside CI the
+  base is `~/.adaptive-task/worktrees/<project_id>`. Parse failures in
+  `pyproject.toml` / `config/worktree.yaml` log a warning and fall back to
+  defaults; they are not distinguishable from "file absent" to callers.
+- **project_id**: `resolve_project_id` returns the declared value unchecked;
+  `resolve_project_id_checked` rejects invalid ids; every function that
+  turns an id into a directory name (`resolve_state_dir_name`) validates it
+  and falls back to `noveler`.
+- **Logging**: `log::debug!` / `log::warn!` for diagnostics; the two
+  `eprintln!` breadcrumbs (`failopen_message`, `suspicious_extra_message`)
+  are frozen by tests and stay on stderr.