From c4fe1c34e628b35f6a93616232c74e98c9607511 Mon Sep 17 00:00:00 2001
From: poli0981 <127664709+poli0981@users.noreply.github.com>
Date: Mon, 27 Jul 2026 17:25:56 +0700
Subject: [PATCH] feat(core): scaffold the Cargo workspace, core crate and CLI
surface
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Phase 0 scaffold per ARCHITECTURE section 2. Everything compiles; nothing
resolves or mutates yet.
Implemented rather than stubbed, because the spikes need them and they are
the parts the invariants rest on:
- errors/catalog.rs: all 30 launch codes with their wire forms, plus tests
that the wire codes are unique and match the PD-- grammar.
Code::ALL drives the future "no code without fixture" gate.
- model.rs: PkgName::parse does PEP 508 validation and PEP 503
normalization. This is the only way a name reaches an argv array, which
makes SECURITY section 2 structural rather than aspirational; the test
table rejects flags, separators and quoting attempts.
- probe.py: stdlib-only, Python 3.10 floor, per ARCHITECTURE section 4.
- The pip/uv argv builders, with tests asserting one token per argument.
- ExecutionSummary::tally, so the "13 successful, 2 failed" headline is
derived from the rows rather than accumulated alongside them.
Stubbed with todo!() and a pointer to the milestone that fills them: the
Engine trait impls, discovery, index, graph, snapshot, pins, health.
UvEngine::parse_dry_run stays unimplemented on purpose — SP-1 must pin
uv's text plan format before anything parses it.
Two findings recorded in spikes/README.md:
- probe.py under -I hides user-site packages: 352 dists vs 376 without it
and 375 from pip list, on a non-venv system Python. Venvs are unaffected.
The fix trades a documented security control against list accuracy, so
it is left as an open SP-6 decision rather than settled here.
- Python 3.14 deprecates subscripting absent metadata headers, which wrote
DeprecationWarning to stderr on most distributions. probe.py now uses
.get(); the probe must stay stderr-clean because noise reads as
PD-ENV-003.
rusqlite is held at 0.37: 0.40 pulls libsqlite3-sys 0.38.1, whose build
script needs the unstable cfg_select! and will not build on stable 1.94.1.
Recorded in the ARCHITECTURE version manifest.
cargo fmt, clippy -D warnings and 23 tests are green.
Co-Authored-By: Claude Opus 5
---
.nvmrc | 1 +
Cargo.lock | 2324 +++++++++++++++++++++
Cargo.toml | 28 +
crates/pipdock-cli/Cargo.toml | 28 +
crates/pipdock-cli/src/main.rs | 385 ++++
crates/pipdock-core/Cargo.toml | 26 +
crates/pipdock-core/src/engine/mod.rs | 105 +
crates/pipdock-core/src/engine/pip.rs | 176 ++
crates/pipdock-core/src/engine/uv.rs | 167 ++
crates/pipdock-core/src/envs/mod.rs | 52 +
crates/pipdock-core/src/errors/catalog.rs | 303 +++
crates/pipdock-core/src/errors/mod.rs | 104 +
crates/pipdock-core/src/graph/mod.rs | 31 +
crates/pipdock-core/src/health/mod.rs | 25 +
crates/pipdock-core/src/index/mod.rs | 28 +
crates/pipdock-core/src/lib.rs | 52 +
crates/pipdock-core/src/model.rs | 328 +++
crates/pipdock-core/src/pins/mod.rs | 26 +
crates/pipdock-core/src/plan/mod.rs | 279 +++
crates/pipdock-core/src/probe.py | 142 ++
crates/pipdock-core/src/snapshot/mod.rs | 23 +
docs/ARCHITECTURE.md | 1 +
rust-toolchain.toml | 5 +
spikes/README.md | 58 +
24 files changed, 4697 insertions(+)
create mode 100644 .nvmrc
create mode 100644 Cargo.lock
create mode 100644 Cargo.toml
create mode 100644 crates/pipdock-cli/Cargo.toml
create mode 100644 crates/pipdock-cli/src/main.rs
create mode 100644 crates/pipdock-core/Cargo.toml
create mode 100644 crates/pipdock-core/src/engine/mod.rs
create mode 100644 crates/pipdock-core/src/engine/pip.rs
create mode 100644 crates/pipdock-core/src/engine/uv.rs
create mode 100644 crates/pipdock-core/src/envs/mod.rs
create mode 100644 crates/pipdock-core/src/errors/catalog.rs
create mode 100644 crates/pipdock-core/src/errors/mod.rs
create mode 100644 crates/pipdock-core/src/graph/mod.rs
create mode 100644 crates/pipdock-core/src/health/mod.rs
create mode 100644 crates/pipdock-core/src/index/mod.rs
create mode 100644 crates/pipdock-core/src/lib.rs
create mode 100644 crates/pipdock-core/src/model.rs
create mode 100644 crates/pipdock-core/src/pins/mod.rs
create mode 100644 crates/pipdock-core/src/plan/mod.rs
create mode 100644 crates/pipdock-core/src/probe.py
create mode 100644 crates/pipdock-core/src/snapshot/mod.rs
create mode 100644 rust-toolchain.toml
create mode 100644 spikes/README.md
diff --git a/.nvmrc b/.nvmrc
new file mode 100644
index 0000000..a45fd52
--- /dev/null
+++ b/.nvmrc
@@ -0,0 +1 @@
+24
diff --git a/Cargo.lock b/Cargo.lock
new file mode 100644
index 0000000..fa019d6
--- /dev/null
+++ b/Cargo.lock
@@ -0,0 +1,2324 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "assert_cmd"
+version = "2.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2aa3a22042e45de04255c7bf3626e239f450200fd0493c1e382263544b20aea6"
+dependencies = [
+ "anstyle",
+ "bstr",
+ "libc",
+ "predicates",
+ "predicates-core",
+ "predicates-tree",
+ "wait-timeout",
+]
+
+[[package]]
+name = "async-compression"
+version = "0.4.42"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e79b3f8a79cccc2898f31920fc69f304859b3bd567490f75ebf51ae1c792a9ac"
+dependencies = [
+ "compression-codecs",
+ "compression-core",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "async-trait"
+version = "0.1.91"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae36dc4177970ef04fde5178d3e2429882def40e57a451f919c098f72baa6cec"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "atomic-waker"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
+
+[[package]]
+name = "aws-lc-rs"
+version = "1.17.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "00bdb5da18dac48ca2cc7cd4a98e533e8635a58e2361d13a1a4ee3888e0d72f1"
+dependencies = [
+ "aws-lc-sys",
+ "zeroize",
+]
+
+[[package]]
+name = "aws-lc-sys"
+version = "0.43.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43103168cc76fe62678a375e722fc9cb3a0146159ac5828bc4f0dfd755c2224c"
+dependencies = [
+ "cc",
+ "cmake",
+ "dunce",
+ "fs_extra",
+ "pkg-config",
+]
+
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "bstr"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f7dc094d718f2e1c1559ad110e27eeaae14a5465d3d56dd6dbd793079fbd530"
+dependencies = [
+ "memchr",
+ "regex-automata",
+ "serde_core",
+]
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+
+[[package]]
+name = "bytes"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
+
+[[package]]
+name = "cc"
+version = "1.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9"
+dependencies = [
+ "find-msvc-tools",
+ "jobserver",
+ "libc",
+ "shlex",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "cfg_aliases"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
+
+[[package]]
+name = "chacha20"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d524456ba66e72eb8b115ff89e01e497f8e6d11d78b70b1aa13c0fbd97540a81"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "rand_core",
+]
+
+[[package]]
+name = "clap"
+version = "4.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d91e0c145792ef73a6ad36d27c75ac09f1832222a3c209689d90f534685ee5b7"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f09628afdcc538b57f3c6341e9c8e9970f18e4a481690a64974d7023bd33548b"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d012d2b9d65aca7f18f4d9878a045bc17899bba951561ba5ec3c2ba1eed9a061"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
+[[package]]
+name = "cmake"
+version = "0.1.58"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c0f78a02292a74a88ac736019ab962ece0bc380e3f977bf72e376c5d78ff0678"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
+[[package]]
+name = "combine"
+version = "4.6.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba5a308b75df32fe02788e748662718f03fde005016435c444eea572398219fd"
+dependencies = [
+ "bytes",
+ "memchr",
+]
+
+[[package]]
+name = "compression-codecs"
+version = "0.4.38"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce2548391e9c1929c21bf6aa2680af86fe4c1b33e6cea9ac1cfeec0bd11218cf"
+dependencies = [
+ "compression-core",
+ "flate2",
+ "memchr",
+]
+
+[[package]]
+name = "compression-core"
+version = "0.4.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc14f565cf027a105f7a44ccf9e5b424348421a1d8952a8fc9d499d313107789"
+
+[[package]]
+name = "console"
+version = "0.16.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fe5f465a4f6fee88fad41b85d990f84c835335e85b5d9e6e63e0d06d28cba7c"
+dependencies = [
+ "encode_unicode",
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "core-foundation"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
+[[package]]
+name = "cpufeatures"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "crc32fast"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5181e0de7b61eb03a81e347d6dd8797bae9da5146707b51077e2d71a54ec0ceb"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d6914041f254d6e9176c01941b21115dcfb7089e55135a35411081bd106ef3f"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61803da095bee82a81bb1a452ecc25d3b2f1416d1897eb86430c6159ef717c17"
+
+[[package]]
+name = "difflib"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6184e33543162437515c2e2b48714794e37845ec9851711914eec9d308f6ebe8"
+
+[[package]]
+name = "displaydoc"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "dunce"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813"
+
+[[package]]
+name = "either"
+version = "1.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e5e8f6c15a24b9a3ee5efec809ccd006d3b30e8b3bb63c39af737c7f87daa1d"
+
+[[package]]
+name = "encode_unicode"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34aa73646ffb006b8f5147f3dc182bd4bcb190227ce861fc4a4844bf8e3cb2c0"
+
+[[package]]
+name = "encoding_rs"
+version = "0.8.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75030f3c4f45dafd7586dd6780965a8c7e8e285a5ecb86713e63a79c5b2766f3"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "fallible-iterator"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2acce4a10f12dc2fb14a218589d4f1f62ef011b2d0cc4b3cb1bba8e94da14649"
+
+[[package]]
+name = "fallible-streaming-iterator"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a"
+
+[[package]]
+name = "fastrand"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+
+[[package]]
+name = "flate2"
+version = "1.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide",
+]
+
+[[package]]
+name = "fnv"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+
+[[package]]
+name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+
+[[package]]
+name = "form_urlencoded"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
+dependencies = [
+ "percent-encoding",
+]
+
+[[package]]
+name = "fs_extra"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"
+
+[[package]]
+name = "futures-channel"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "262590f4fe6afeb0bc83be1daa64e52657fe185690a958af7f3ad0e92085c5ae"
+dependencies = [
+ "futures-core",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7"
+
+[[package]]
+name = "futures-sink"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e34418ac499d6305c2fb5ad0ed2f6ac998c5f8ca209b4510f7f94242c647e307"
+
+[[package]]
+name = "futures-task"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109"
+
+[[package]]
+name = "futures-util"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "js-sys",
+ "libc",
+ "wasi",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
+dependencies = [
+ "cfg-if",
+ "js-sys",
+ "libc",
+ "r-efi",
+ "rand_core",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "h2"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6cb093c84e8bd9b188d4c4a8cb6579fc016968d14c99882163cd3ff402a4f155"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "fnv",
+ "futures-core",
+ "futures-sink",
+ "http",
+ "indexmap",
+ "slab",
+ "tokio",
+ "tokio-util",
+ "tracing",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "foldhash",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "hashlink"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7382cf6263419f2d8df38c55d7da83da5c18aef87fc7a7fc1fb1e344edfe14c1"
+dependencies = [
+ "hashbrown 0.15.5",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "http"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6970f50e31d6fc17d3fa27329444bfa74e196cf62e95052a3f6fee181dba6425"
+dependencies = [
+ "bytes",
+ "itoa",
+]
+
+[[package]]
+name = "http-body"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c"
+dependencies = [
+ "bytes",
+ "http",
+]
+
+[[package]]
+name = "http-body-util"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e9f41fd6a08e4d4ec69df65976da761afd5ad5e58a9d4acb46bd1c953a9e3ff2"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "httparse"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
+
+[[package]]
+name = "hyper"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d22053281f852e11534f5198498373cbb59295120a20771d90f7ed1897490a72"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "futures-channel",
+ "futures-core",
+ "h2",
+ "http",
+ "http-body",
+ "httparse",
+ "itoa",
+ "pin-project-lite",
+ "smallvec",
+ "tokio",
+ "want",
+]
+
+[[package]]
+name = "hyper-rustls"
+version = "0.27.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f"
+dependencies = [
+ "http",
+ "hyper",
+ "hyper-util",
+ "rustls",
+ "tokio",
+ "tokio-rustls",
+ "tower-service",
+]
+
+[[package]]
+name = "hyper-util"
+version = "0.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
+dependencies = [
+ "base64",
+ "bytes",
+ "futures-channel",
+ "futures-util",
+ "http",
+ "http-body",
+ "hyper",
+ "ipnet",
+ "libc",
+ "percent-encoding",
+ "pin-project-lite",
+ "socket2",
+ "tokio",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "icu_collections"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2984d1cd16c883d7935b9e07e44071dca8d917fd52ecc02c04d5fa0b5a3f191c"
+dependencies = [
+ "displaydoc",
+ "potential_utf",
+ "utf8_iter",
+ "yoke",
+ "zerofrom",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_locale_core"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29"
+dependencies = [
+ "displaydoc",
+ "litemap",
+ "tinystr",
+ "writeable",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c56e5ee99d6e3d33bd91c5d85458b6005a22140021cc324cea84dd0e72cff3b4"
+dependencies = [
+ "icu_collections",
+ "icu_normalizer_data",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da3be0ae77ea334f4da67c12f149704f19f81d1adf7c51cf482943e84a2bad38"
+
+[[package]]
+name = "icu_properties"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bee3b67d0ea5c2cca5003417989af8996f8604e34fb9ddf96208a033901e70de"
+dependencies = [
+ "icu_collections",
+ "icu_locale_core",
+ "icu_properties_data",
+ "icu_provider",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_properties_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e2bbb201e0c04f7b4b3e14382af113e17ba4f63e2c9d2ee626b720cbce54a14"
+
+[[package]]
+name = "icu_provider"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421"
+dependencies = [
+ "displaydoc",
+ "icu_locale_core",
+ "writeable",
+ "yoke",
+ "zerofrom",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "idna"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
+dependencies = [
+ "idna_adapter",
+ "smallvec",
+ "utf8_iter",
+]
+
+[[package]]
+name = "idna_adapter"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
+dependencies = [
+ "icu_normalizer",
+ "icu_properties",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
+dependencies = [
+ "equivalent",
+ "hashbrown 0.17.1",
+]
+
+[[package]]
+name = "insta"
+version = "1.48.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "86f0f8fee8c926415c58d6ae43a08523a26faccb2323f5e6b644fe7dd4ef6b82"
+dependencies = [
+ "console",
+ "once_cell",
+ "serde",
+ "similar",
+ "tempfile",
+]
+
+[[package]]
+name = "ipnet"
+version = "2.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"
+
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "jni"
+version = "0.22.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5efd9a482cf3a427f00d6b35f14332adc7902ce91efb778580e180ff90fa3498"
+dependencies = [
+ "cfg-if",
+ "combine",
+ "jni-macros",
+ "jni-sys",
+ "log",
+ "simd_cesu8",
+ "thiserror",
+ "walkdir",
+ "windows-link",
+]
+
+[[package]]
+name = "jni-macros"
+version = "0.22.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a00109accc170f0bdb141fed3e393c565b6f5e072365c3bd58f5b062591560a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "rustc_version",
+ "simd_cesu8",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "jni-sys"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6377a88cb3910bee9b0fa88d4f42e1d2da8e79915598f65fb0c7ee14c878af2"
+dependencies = [
+ "jni-sys-macros",
+]
+
+[[package]]
+name = "jni-sys-macros"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38c0b942f458fe50cdac086d2f946512305e5631e720728f2a61aabcd47a6264"
+dependencies = [
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "jobserver"
+version = "0.1.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c00acbd29eabad4a2392fa0e921c874934dbbf4194312ad20f04a0ed67a3cb3"
+dependencies = [
+ "getrandom 0.4.3",
+ "libc",
+]
+
+[[package]]
+name = "js-sys"
+version = "0.3.103"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "libsqlite3-sys"
+version = "0.35.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "133c182a6a2c87864fe97778797e46c7e999672690dc9fa3ee8e241aa4a9c13f"
+dependencies = [
+ "cc",
+ "pkg-config",
+ "vcpkg",
+]
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
+[[package]]
+name = "litemap"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
+
+[[package]]
+name = "lock_api"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
+dependencies = [
+ "scopeguard",
+]
+
+[[package]]
+name = "log"
+version = "0.4.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
+
+[[package]]
+name = "lru-slab"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "112b39cec0b298b6c1999fee3e31427f74f676e4cb9879ed1a121b43661a4154"
+
+[[package]]
+name = "matchers"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d1525a2a28c7f4fa0fc98bb91ae755d1e2d1505079e05539e35bc876b5d65ae9"
+dependencies = [
+ "regex-automata",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "mime"
+version = "0.3.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a"
+
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "mio"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30d65c71f1ce40ab09135ce117d742b9f8a19ff91a41a8b57ed50bc2de59c427"
+dependencies = [
+ "libc",
+ "wasi",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "nu-ansi-term"
+version = "0.50.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "nucleo"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5262af4c94921c2646c5ac6ff7900c2af9cbb08dc26a797e18130a7019c039d4"
+dependencies = [
+ "nucleo-matcher",
+ "parking_lot",
+ "rayon",
+]
+
+[[package]]
+name = "nucleo-matcher"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf33f538733d1a5a3494b836ba913207f14d9d4a1d3cd67030c5061bdd2cac85"
+dependencies = [
+ "memchr",
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
+[[package]]
+name = "openssl-probe"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe"
+
+[[package]]
+name = "parking_lot"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a"
+dependencies = [
+ "lock_api",
+ "parking_lot_core",
+]
+
+[[package]]
+name = "parking_lot_core"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-link",
+]
+
+[[package]]
+name = "percent-encoding"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "pipdock-cli"
+version = "0.1.0"
+dependencies = [
+ "assert_cmd",
+ "clap",
+ "insta",
+ "pipdock-core",
+ "serde_json",
+ "tokio",
+ "tracing",
+ "tracing-subscriber",
+]
+
+[[package]]
+name = "pipdock-core"
+version = "0.1.0"
+dependencies = [
+ "async-trait",
+ "insta",
+ "nucleo",
+ "reqwest",
+ "rusqlite",
+ "serde",
+ "serde_json",
+ "thiserror",
+ "tokio",
+ "tracing",
+]
+
+[[package]]
+name = "pkg-config"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"
+
+[[package]]
+name = "potential_utf"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"
+dependencies = [
+ "zerovec",
+]
+
+[[package]]
+name = "predicates"
+version = "3.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ada8f2932f28a27ee7b70dd6c1c39ea0675c55a36879ab92f3a715eaa1e63cfe"
+dependencies = [
+ "anstyle",
+ "difflib",
+ "predicates-core",
+]
+
+[[package]]
+name = "predicates-core"
+version = "1.0.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cad38746f3166b4031b1a0d39ad9f954dd291e7854fcc0eed52ee41a0b50d144"
+
+[[package]]
+name = "predicates-tree"
+version = "1.0.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0de1b847b39c8131db0467e9df1ff60e6d0562ab8e9a16e568ad0fdb372e2f2"
+dependencies = [
+ "predicates-core",
+ "termtree",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quinn"
+version = "0.11.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c1a41e437b6bbd489372cd4971de128e85c855f56c57f283d20ff016cf7c0a8"
+dependencies = [
+ "bytes",
+ "cfg_aliases",
+ "pin-project-lite",
+ "quinn-proto",
+ "quinn-udp",
+ "rustc-hash",
+ "rustls",
+ "socket2",
+ "thiserror",
+ "tokio",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-proto"
+version = "0.11.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f4bfc015262b9df63c8845072ce59068853ff5872180c2ce2f13038b970e560"
+dependencies = [
+ "aws-lc-rs",
+ "bytes",
+ "getrandom 0.4.3",
+ "lru-slab",
+ "rand",
+ "rand_pcg",
+ "ring",
+ "rustc-hash",
+ "rustls",
+ "rustls-pki-types",
+ "slab",
+ "thiserror",
+ "tinyvec",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-udp"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "35a133f956daabe89a61a685c2649f13d82d5aa4bd5d12d1277e1072a21c0694"
+dependencies = [
+ "cfg_aliases",
+ "libc",
+ "once_cell",
+ "socket2",
+ "tracing",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+
+[[package]]
+name = "rand"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c7f5fa3a058cd35567ef9bfa5e75732bee0f9e4c55fa90477bef2dfcdbc4be80"
+dependencies = [
+ "chacha20",
+ "getrandom 0.4.3",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
+
+[[package]]
+name = "rand_pcg"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "caa0f4137e1c0a72f4c651489402276c8e8e1cf081f3b0ba156d2cbeef09e86a"
+dependencies = [
+ "rand_core",
+]
+
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "redox_syscall"
+version = "0.5.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
+dependencies = [
+ "bitflags",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "reqwest"
+version = "0.13.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "219c5811de6525e5416c7d5d53bb656d3afdbc6c5af816e0802bcfa42dbdc1c3"
+dependencies = [
+ "base64",
+ "bytes",
+ "encoding_rs",
+ "futures-core",
+ "h2",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-rustls",
+ "hyper-util",
+ "js-sys",
+ "log",
+ "mime",
+ "percent-encoding",
+ "pin-project-lite",
+ "quinn",
+ "rustls",
+ "rustls-pki-types",
+ "rustls-platform-verifier",
+ "serde",
+ "serde_json",
+ "sync_wrapper",
+ "tokio",
+ "tokio-rustls",
+ "tower",
+ "tower-http",
+ "tower-service",
+ "url",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
+[[package]]
+name = "ring"
+version = "0.17.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
+dependencies = [
+ "cc",
+ "cfg-if",
+ "getrandom 0.2.17",
+ "libc",
+ "untrusted",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "rusqlite"
+version = "0.37.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "165ca6e57b20e1351573e3729b958bc62f0e48025386970b6e4d29e7a7e71f3f"
+dependencies = [
+ "bitflags",
+ "fallible-iterator",
+ "fallible-streaming-iterator",
+ "hashlink",
+ "libsqlite3-sys",
+ "smallvec",
+]
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "rustc_version"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92"
+dependencies = [
+ "semver",
+]
+
+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "rustls"
+version = "0.23.42"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c54fcab019b409d04215d3a17cb438fd7fbf192ee61461f20f4fe18704bc138"
+dependencies = [
+ "aws-lc-rs",
+ "once_cell",
+ "rustls-pki-types",
+ "rustls-webpki",
+ "subtle",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-native-certs"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dab5152771c58876a2146916e53e35057e1a4dfa2b9df0f0305b07f611fdea4d"
+dependencies = [
+ "openssl-probe",
+ "rustls-pki-types",
+ "schannel",
+ "security-framework",
+]
+
+[[package]]
+name = "rustls-pki-types"
+version = "1.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96"
+dependencies = [
+ "web-time",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-platform-verifier"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "26d1e2536ce4f35f4846aa13bff16bd0ff40157cdb14cc056c7b14ba41233ba0"
+dependencies = [
+ "core-foundation",
+ "core-foundation-sys",
+ "jni",
+ "log",
+ "once_cell",
+ "rustls",
+ "rustls-native-certs",
+ "rustls-platform-verifier-android",
+ "rustls-webpki",
+ "security-framework",
+ "security-framework-sys",
+ "webpki-root-certs",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "rustls-platform-verifier-android"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f87165f0995f63a9fbeea62b64d10b4d9d8e78ec6d7d51fb2125fda7bb36788f"
+
+[[package]]
+name = "rustls-webpki"
+version = "0.103.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
+dependencies = [
+ "aws-lc-rs",
+ "ring",
+ "rustls-pki-types",
+ "untrusted",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
+[[package]]
+name = "schannel"
+version = "0.1.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91c1b7e4904c873ef0710c1f407dde2e6287de2bebc1bbbf7d430bb7cbffd939"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
+[[package]]
+name = "security-framework"
+version = "3.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
+dependencies = [
+ "bitflags",
+ "core-foundation",
+ "core-foundation-sys",
+ "libc",
+ "security-framework-sys",
+]
+
+[[package]]
+name = "security-framework-sys"
+version = "2.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.151"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "sharded-slab"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f40ca3c46823713e0d4209592e8d6e826aa57e928f09752619fc696c499637f6"
+dependencies = [
+ "lazy_static",
+]
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+
+[[package]]
+name = "simd-adler32"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
+
+[[package]]
+name = "simd_cesu8"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11031e251abf8611c80f460e19dbdeb54a66db918e49c65a7065b46ac7aec520"
+dependencies = [
+ "rustc_version",
+ "simdutf8",
+]
+
+[[package]]
+name = "simdutf8"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e"
+
+[[package]]
+name = "similar"
+version = "2.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbbb5d9659141646ae647b42fe094daf6c6192d1620870b449d9557f748b2daa"
+
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "smallvec"
+version = "1.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+
+[[package]]
+name = "socket2"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "subtle"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "sync_wrapper"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"
+dependencies = [
+ "futures-core",
+]
+
+[[package]]
+name = "synstructure"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom 0.4.3",
+ "once_cell",
+ "rustix",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "termtree"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f50febec83f5ee1df3015341d8bd429f2d1cc62bcba7ea2076759d315084683"
+
+[[package]]
+name = "thiserror"
+version = "2.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "thread_local"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ad99c4c6d32803332c548b1af0540b357b3f5fc0be8f6c6bfe8b2e6ae784070"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "tinystr"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"
+dependencies = [
+ "displaydoc",
+ "zerovec",
+]
+
+[[package]]
+name = "tinyvec"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb4ebadaa0af04fab11ae01eb5f9fdb5f9c5b875506e210e71c07873528baa7f"
+dependencies = [
+ "tinyvec_macros",
+]
+
+[[package]]
+name = "tinyvec_macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
+
+[[package]]
+name = "tokio"
+version = "1.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
+dependencies = [
+ "bytes",
+ "libc",
+ "mio",
+ "pin-project-lite",
+ "signal-hook-registry",
+ "socket2",
+ "tokio-macros",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "tokio-macros"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6328af13490e73a9b4694030fafd93f8c8c6a9dede33e821c3fc63eddf8042ba"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "tokio-rustls"
+version = "0.26.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1729aa945f29d91ba541258c8df89027d5792d85a8841fb65e8bf0f4ede4ef61"
+dependencies = [
+ "rustls",
+ "tokio",
+]
+
+[[package]]
+name = "tokio-util"
+version = "0.7.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "futures-sink",
+ "libc",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "tower"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4"
+dependencies = [
+ "futures-core",
+ "futures-util",
+ "pin-project-lite",
+ "sync_wrapper",
+ "tokio",
+ "tower-layer",
+ "tower-service",
+]
+
+[[package]]
+name = "tower-http"
+version = "0.6.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
+dependencies = [
+ "async-compression",
+ "bitflags",
+ "bytes",
+ "futures-core",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "pin-project-lite",
+ "tokio",
+ "tokio-util",
+ "tower",
+ "tower-layer",
+ "tower-service",
+ "url",
+]
+
+[[package]]
+name = "tower-layer"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e"
+
+[[package]]
+name = "tower-service"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3"
+
+[[package]]
+name = "tracing"
+version = "0.1.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
+dependencies = [
+ "pin-project-lite",
+ "tracing-attributes",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-attributes"
+version = "0.1.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "tracing-core"
+version = "0.1.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+ "valuable",
+]
+
+[[package]]
+name = "tracing-log"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee855f1f400bd0e5c02d150ae5de3840039a3f54b025156404e34c23c03f47c3"
+dependencies = [
+ "log",
+ "once_cell",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-subscriber"
+version = "0.3.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb7f578e5945fb242538965c2d0b04418d38ec25c79d160cd279bf0731c8d319"
+dependencies = [
+ "matchers",
+ "nu-ansi-term",
+ "once_cell",
+ "regex-automata",
+ "sharded-slab",
+ "smallvec",
+ "thread_local",
+ "tracing",
+ "tracing-core",
+ "tracing-log",
+]
+
+[[package]]
+name = "try-lock"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
+
+[[package]]
+name = "untrusted"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
+
+[[package]]
+name = "url"
+version = "2.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
+dependencies = [
+ "form_urlencoded",
+ "idna",
+ "percent-encoding",
+ "serde",
+]
+
+[[package]]
+name = "utf8_iter"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
+
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
+[[package]]
+name = "valuable"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
+
+[[package]]
+name = "vcpkg"
+version = "0.2.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426"
+
+[[package]]
+name = "wait-timeout"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ac3b126d3914f9849036f826e054cbabdc8519970b8998ddaf3b5bd3c65f11"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "walkdir"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
+dependencies = [
+ "same-file",
+ "winapi-util",
+]
+
+[[package]]
+name = "want"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
+dependencies = [
+ "try-lock",
+]
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-futures"
+version = "0.4.76"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c62df1340f32221cb9c54d6a27b030e3dba64361d4a95bed55f9aacb44da291d"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "web-sys"
+version = "0.3.103"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8622dcb61c0bcc9fffa6938bed81210af2da9a7e4a1a834b2e37a59b6dfb6141"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "web-time"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "webpki-root-certs"
+version = "1.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b96554aa2acc8ccdb7e1c9a58a7a68dd5d13bccc69cd124cb09406db612a1c9b"
+dependencies = [
+ "rustls-pki-types",
+]
+
+[[package]]
+name = "winapi-util"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm",
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
+ "windows_i686_gnullvm",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_gnullvm",
+ "windows_x86_64_msvc",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
+[[package]]
+name = "writeable"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
+
+[[package]]
+name = "yoke"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
+dependencies = [
+ "stable_deref_trait",
+ "yoke-derive",
+ "zerofrom",
+]
+
+[[package]]
+name = "yoke-derive"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "synstructure",
+]
+
+[[package]]
+name = "zerofrom"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
+dependencies = [
+ "zerofrom-derive",
+]
+
+[[package]]
+name = "zerofrom-derive"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "synstructure",
+]
+
+[[package]]
+name = "zeroize"
+version = "1.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
+
+[[package]]
+name = "zerotrie"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf"
+dependencies = [
+ "displaydoc",
+ "yoke",
+ "zerofrom",
+]
+
+[[package]]
+name = "zerovec"
+version = "0.11.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"
+dependencies = [
+ "yoke",
+ "zerofrom",
+ "zerovec-derive",
+]
+
+[[package]]
+name = "zerovec-derive"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
diff --git a/Cargo.toml b/Cargo.toml
new file mode 100644
index 0000000..ab5e222
--- /dev/null
+++ b/Cargo.toml
@@ -0,0 +1,28 @@
+[workspace]
+resolver = "3"
+members = ["crates/pipdock-core", "crates/pipdock-cli"]
+
+[workspace.package]
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.94"
+license = "GPL-3.0-only"
+repository = "https://github.com/poli0981/pipdock"
+authors = ["Kokone (poli0981)"]
+
+[workspace.lints.rust]
+unsafe_code = "forbid"
+
+[workspace.lints.clippy]
+# The five hard invariants in CLAUDE.md are about *not* taking shortcuts around
+# the engine. These lints are the mechanical half of enforcing that.
+todo = "allow" # scaffold phase; flip to "warn" once M1 lands
+dbg_macro = "deny"
+print_stdout = "deny" # core is a library: emit events, never println
+unwrap_used = "deny"
+expect_used = "deny"
+
+[profile.release]
+strip = true
+lto = true
+codegen-units = 1
diff --git a/crates/pipdock-cli/Cargo.toml b/crates/pipdock-cli/Cargo.toml
new file mode 100644
index 0000000..dca379b
--- /dev/null
+++ b/crates/pipdock-cli/Cargo.toml
@@ -0,0 +1,28 @@
+[package]
+name = "pipdock-cli"
+description = "The `pipdock` command-line interface."
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+authors.workspace = true
+
+[[bin]]
+name = "pipdock"
+path = "src/main.rs"
+
+[lints]
+workspace = true
+
+[dependencies]
+clap = { version = "4.6.4", features = ["derive"] }
+pipdock-core = { path = "../pipdock-core" }
+serde_json = "1.0.151"
+tokio = { version = "1.53.1", features = ["rt-multi-thread", "macros"] }
+tracing = "0.1.44"
+tracing-subscriber = { version = "0.3.23", features = ["env-filter"] }
+
+[dev-dependencies]
+assert_cmd = "2.2.2"
+insta = "1.48.0"
diff --git a/crates/pipdock-cli/src/main.rs b/crates/pipdock-cli/src/main.rs
new file mode 100644
index 0000000..ece65d8
--- /dev/null
+++ b/crates/pipdock-cli/src/main.rs
@@ -0,0 +1,385 @@
+//! `pipdock` — the command-line head over `pipdock-core`.
+//!
+//! CLI-SPEC §1.1: every command maps 1:1 onto the core functions the GUI uses; **the CLI adds no
+//! logic of its own**. CLI-SPEC §1.2: safe by default — off a TTY, or with `--yes`, conflicts
+//! default to *skip*, never *force*.
+//!
+//! English-only in v1 (I18N §1); messages reuse catalog codes so they stay greppable.
+
+// The CLI is the one place that legitimately writes to stdout; the core never does.
+#![allow(clippy::print_stdout, clippy::print_stderr)]
+
+use std::path::PathBuf;
+use std::process::ExitCode;
+
+use clap::{Args, Parser, Subcommand, ValueEnum};
+
+/// Exit codes, exhaustively specified in CLI-SPEC §5.
+///
+/// Scripts pin against these, so the numbers are a public contract.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u8)]
+pub enum Exit {
+ /// All steps succeeded.
+ Success = 0,
+ /// Completed with per-package failures; see `counts.failed` in `--json`.
+ PartialFailure = 1,
+ /// Plan aborted — resolution impossible and the skip policy removed everything.
+ PlanAborted = 2,
+ /// Environment error, including a PEP 668 block (`PD-ENV-*`).
+ EnvError = 3,
+ /// Engine unavailable or too old (`PD-ENG-*`).
+ EngineError = 4,
+ /// Snapshot failure — **nothing was executed** (`PD-SNP-001`).
+ SnapshotError = 5,
+ /// Network or index error (`PD-NET-*`).
+ NetworkError = 6,
+ /// Internal error (`PD-INT-*`); the log path is printed.
+ Internal = 10,
+ /// User cancelled; child processes reaped and a partial summary printed.
+ Cancelled = 130,
+}
+
+impl From for ExitCode {
+ fn from(e: Exit) -> Self {
+ Self::from(e as u8)
+ }
+}
+
+/// Conflict-handling strategy for `update` and `install`.
+#[derive(Debug, Clone, Copy, ValueEnum)]
+pub enum StrategyArg {
+ /// Accept the resolver's compatible version. The safe default.
+ Compatible,
+ /// Force the latest version. Off a TTY this requires an explicit acknowledgement.
+ Latest,
+}
+
+/// Which engine to drive.
+#[derive(Debug, Clone, Copy, ValueEnum)]
+pub enum EngineArg {
+ /// ` -m pip`
+ Pip,
+ /// `uv pip --python `
+ Uv,
+}
+
+/// Options accepted by every command (CLI-SPEC §2).
+#[derive(Debug, Args)]
+pub struct GlobalOpts {
+ /// Interpreter or environment directory. Defaults to the last used env, else an
+ /// auto-detected `.venv` in the working directory.
+ #[arg(long, global = true, value_name = "PATH")]
+ pub env: Option,
+
+ /// Override the configured engine for this invocation.
+ #[arg(long, global = true, value_enum)]
+ pub engine: Option,
+
+ /// Machine-readable output; NDJSON for streaming commands.
+ #[arg(long, global = true)]
+ pub json: bool,
+
+ /// Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*.
+ #[arg(long, short = 'y', global = true)]
+ pub yes: bool,
+
+ /// Reduce log output.
+ #[arg(long, global = true, conflicts_with = "verbose")]
+ pub quiet: bool,
+
+ /// Increase log output.
+ #[arg(long, global = true)]
+ pub verbose: bool,
+
+ /// Tee logs to a file.
+ #[arg(long, global = true, value_name = "PATH")]
+ pub log_file: Option,
+
+ /// DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
+ ///
+ /// This is the sole documented escape from DATA-FLOW §9.2, and it exists because a
+ /// throwaway CI container has nothing to roll back to.
+ #[arg(long, global = true)]
+ pub no_snapshot: bool,
+}
+
+#[derive(Debug, Parser)]
+#[command(
+ name = "pipdock",
+ version,
+ about = "A friendly dock for your Python environments.",
+ long_about = "Inspect, install, update and clean up Python packages in bulk.\n\
+ Every mutating operation is previewed and snapshotted first."
+)]
+struct Cli {
+ #[command(flatten)]
+ global: GlobalOpts,
+
+ #[command(subcommand)]
+ command: Command,
+}
+
+/// The command surface, per CLI-SPEC §3.
+#[derive(Debug, Subcommand)]
+enum Command {
+ /// Manage environments.
+ #[command(subcommand)]
+ Env(EnvCommand),
+
+ /// List installed packages.
+ List {
+ /// Show only packages with a newer release available.
+ #[arg(long)]
+ outdated: bool,
+ },
+
+ /// Fuzzy-search the local PyPI name index.
+ Search {
+ /// Query string.
+ query: String,
+ /// Maximum results.
+ #[arg(long, default_value_t = 20)]
+ limit: usize,
+ },
+
+ /// Show cached PyPI metadata for a package.
+ Info {
+ /// Package name.
+ pkg: String,
+ },
+
+ /// Install packages.
+ Install {
+ /// `name` or `name==version`.
+ #[arg(required = true)]
+ specs: Vec,
+ /// Print the resolution report and exit without changing anything.
+ #[arg(long)]
+ dry_run: bool,
+ },
+
+ /// Update packages.
+ Update {
+ /// Packages to update; omit and pass `--all` for everything.
+ pkgs: Vec,
+ /// Update every outdated package (pins still apply).
+ #[arg(long, conflicts_with = "pkgs")]
+ all: bool,
+ /// Conflict strategy.
+ #[arg(long, value_enum, default_value = "compatible")]
+ strategy: StrategyArg,
+ /// Ad-hoc exclusions on top of the pin list.
+ #[arg(long, value_delimiter = ',', value_name = "PKG,...")]
+ except: Vec,
+ /// Print the resolution report and exit without changing anything.
+ #[arg(long)]
+ dry_run: bool,
+ },
+
+ /// Remove packages, guarded by the reverse-dependency check.
+ Uninstall {
+ /// Packages to remove.
+ #[arg(required = true)]
+ pkgs: Vec,
+ /// Proceed even when the guard reports dependents that would break.
+ #[arg(long)]
+ force: bool,
+ },
+
+ /// Manage the per-environment pin list.
+ #[command(subcommand)]
+ Pin(PinCommand),
+
+ /// Manage snapshots.
+ #[command(subcommand)]
+ Snapshot(SnapshotCommand),
+
+ /// Engine check and environment sanity report.
+ Doctor,
+
+ /// Run Code Health (deptry / vulture / ruff) over a project folder.
+ Health {
+ /// Project folder; defaults to the folder remembered for this environment.
+ #[arg(long, value_name = "DIR")]
+ path: Option,
+ /// Run a single tool instead of all three.
+ #[arg(long)]
+ tool: Option,
+ /// Apply ruff's safe fixes. Prompts before writing.
+ #[arg(long)]
+ fix: bool,
+ },
+
+ /// Upgrade pip inside the selected environment.
+ PipUpgrade,
+
+ /// Show or set the configured engine.
+ Engine {
+ /// Engine to switch to; omit to print the current one.
+ engine: Option,
+ },
+
+ /// Index maintenance.
+ #[command(subcommand)]
+ Index(IndexCommand),
+
+ /// Print the JSON Schema for a core type so scripts can pin against it.
+ Schema {
+ /// Type name, e.g. `ResolutionReport`.
+ type_name: String,
+ },
+
+ /// Self-service helpers.
+ #[command(subcommand, name = "self")]
+ Selfx(SelfCommand),
+}
+
+#[derive(Debug, Subcommand)]
+enum EnvCommand {
+ /// List discovered environments, their sources and PEP 668 flags.
+ List,
+ /// Set the default environment.
+ Use {
+ /// Interpreter or environment directory.
+ path: PathBuf,
+ },
+}
+
+#[derive(Debug, Subcommand)]
+enum PinCommand {
+ /// Pin a package so bulk updates skip it.
+ Add {
+ /// Package name.
+ pkg: String,
+ /// Why it is pinned.
+ #[arg(long)]
+ reason: Option,
+ },
+ /// Remove a pin.
+ Remove {
+ /// Package name.
+ pkg: String,
+ },
+ /// Show the pin list.
+ List,
+}
+
+#[derive(Debug, Subcommand)]
+enum SnapshotCommand {
+ /// List snapshots for the selected environment.
+ List,
+ /// Take a snapshot now.
+ Create,
+ /// Diff a snapshot against the current environment.
+ Diff {
+ /// Snapshot id.
+ id: String,
+ },
+ /// Restore a snapshot.
+ Rollback {
+ /// Snapshot id, or `latest`.
+ id: String,
+ },
+}
+
+#[derive(Debug, Subcommand)]
+enum IndexCommand {
+ /// Re-pull the PEP 691 name index.
+ Refresh,
+}
+
+#[derive(Debug, Subcommand)]
+enum SelfCommand {
+ /// Print a prefilled GitHub issue URL.
+ ReportBug,
+}
+
+fn main() -> ExitCode {
+ let cli = Cli::parse();
+
+ // M1 wires each command to its pipdock-core call. Until then the binary parses its full
+ // surface — which is what the CLI-SPEC §5 exit-code tests and the golden-output tests in
+ // TESTING L4 exercise — and reports honestly that nothing is implemented.
+ let _ = (&cli.global, &cli.command);
+ eprintln!(
+ "error[PD-INT-001]: pipdock is in Phase 0; commands are not implemented yet.\n\
+ The command surface is parsed and stable — see docs/CLI-SPEC.md."
+ );
+ Exit::Internal.into()
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used, clippy::expect_used)]
+mod tests {
+ use super::*;
+ use clap::CommandFactory;
+
+ #[test]
+ fn cli_definition_is_valid() {
+ // Catches conflicting flags, duplicate shorts and bad defaults at test time rather than
+ // at the user's first invocation.
+ Cli::command().debug_assert();
+ }
+
+ #[test]
+ fn exit_codes_match_the_specification() {
+ // CLI-SPEC §5 is a public contract; scripts branch on these numbers.
+ assert_eq!(Exit::Success as u8, 0);
+ assert_eq!(Exit::PartialFailure as u8, 1);
+ assert_eq!(Exit::PlanAborted as u8, 2);
+ assert_eq!(Exit::EnvError as u8, 3);
+ assert_eq!(Exit::EngineError as u8, 4);
+ assert_eq!(Exit::SnapshotError as u8, 5);
+ assert_eq!(Exit::NetworkError as u8, 6);
+ assert_eq!(Exit::Internal as u8, 10);
+ assert_eq!(Exit::Cancelled as u8, 130);
+ }
+
+ #[test]
+ fn update_defaults_to_the_safe_strategy() {
+ let cli = Cli::try_parse_from(["pipdock", "update", "--all"]).unwrap();
+ match cli.command {
+ Command::Update { strategy, all, .. } => {
+ assert!(all);
+ assert!(matches!(strategy, StrategyArg::Compatible));
+ }
+ other => panic!("expected update, got {other:?}"),
+ }
+ }
+
+ #[test]
+ fn documented_examples_parse() {
+ // The three examples in CLI-SPEC §7, verbatim.
+ Cli::try_parse_from([
+ "pipdock",
+ "update",
+ "--all",
+ "--env",
+ r"C:\bots\scraper\.venv",
+ "--yes",
+ "--json",
+ "--log-file",
+ r"C:\logs\pd.json",
+ ])
+ .expect("nightly maintenance example");
+
+ Cli::try_parse_from([
+ "pipdock",
+ "update",
+ "pandas",
+ "numpy",
+ "--dry-run",
+ "--json",
+ ])
+ .expect("audit example");
+
+ Cli::try_parse_from(["pipdock", "uninstall", "legacylib", "--json"])
+ .expect("refuse-to-break example");
+ }
+
+ #[test]
+ fn all_and_explicit_packages_are_mutually_exclusive() {
+ assert!(Cli::try_parse_from(["pipdock", "update", "--all", "numpy"]).is_err());
+ }
+}
diff --git a/crates/pipdock-core/Cargo.toml b/crates/pipdock-core/Cargo.toml
new file mode 100644
index 0000000..a9f97e4
--- /dev/null
+++ b/crates/pipdock-core/Cargo.toml
@@ -0,0 +1,26 @@
+[package]
+name = "pipdock-core"
+description = "Domain logic for PipDock: engine adapters, planning, snapshots, dependency graph."
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+authors.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+async-trait = "0.1.91"
+nucleo = "0.5.0"
+reqwest = { version = "0.13.4", default-features = false, features = ["rustls", "http2", "json", "gzip", "charset"] }
+rusqlite = { version = "0.37", features = ["bundled"] }
+serde = { version = "1.0.229", features = ["derive"] }
+serde_json = "1.0.151"
+thiserror = "2.0.19"
+tokio = { version = "1.53.1", features = ["rt-multi-thread", "macros", "process", "io-util", "time", "sync"] }
+tracing = "0.1.44"
+
+[dev-dependencies]
+insta = { version = "1.48.0", features = ["json"] }
diff --git a/crates/pipdock-core/src/engine/mod.rs b/crates/pipdock-core/src/engine/mod.rs
new file mode 100644
index 0000000..6b23b66
--- /dev/null
+++ b/crates/pipdock-core/src/engine/mod.rs
@@ -0,0 +1,105 @@
+//! The `Engine` trait and its two adapters.
+//!
+//! ARCHITECTURE §1.2: **explain, don't reimplement.** Resolution is always performed by the
+//! selected engine in dry-run mode; this module parses and normalizes, and never computes version
+//! resolution itself.
+//!
+//! ARCHITECTURE §1.5: engines are invoked with argv arrays via `tokio::process::Command`,
+//! **never through a shell**.
+
+pub mod pip;
+pub mod uv;
+
+use async_trait::async_trait;
+
+use crate::errors::Result;
+use crate::model::{
+ CheckReport, Dist, EngineId, EngineInfo, ExecMode, OutdatedDist, PinnedSpec, PkgName, PyEnv,
+ StepResult,
+};
+use crate::plan::{PlanRequest, ResolutionReport};
+
+/// Where live subprocess output goes.
+///
+/// The GUI forwards these to the `plan-progress` Tauri event feeding the console drawer
+/// (ARCHITECTURE §7); the CLI writes them as NDJSON when `--json` is set (CLI-SPEC §6).
+pub type EventSink = tokio::sync::mpsc::UnboundedSender;
+
+/// A line of progress from a running engine command.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct ProgressEvent {
+ /// Zero-based index of the step within the plan.
+ pub step: usize,
+ /// The package this line belongs to, absent for batch-wide output.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub pkg: Option,
+ /// Which execution phase is running.
+ pub phase: ExecMode,
+ /// One line of the engine's stdout or stderr, verbatim and never localized.
+ pub line: String,
+}
+
+/// The contract both adapters implement. See ARCHITECTURE §3.
+#[async_trait]
+pub trait Engine: Send + Sync {
+ /// Which engine this is.
+ fn id(&self) -> EngineId;
+
+ /// Version and availability for `env`.
+ async fn info(&self, env: &PyEnv) -> EngineInfo;
+
+ /// Everything installed in `env`.
+ async fn list_installed(&self, env: &PyEnv) -> Result>;
+
+ /// Installed packages with a newer release available.
+ async fn list_outdated(&self, env: &PyEnv) -> Result>;
+
+ /// Dry-run resolve `req` against `env`, normalized into a [`ResolutionReport`].
+ ///
+ /// This is the only way a plan may be produced; DATA-FLOW §9.1 forbids any mutating call
+ /// without a report accepted in the same session.
+ async fn resolve(&self, env: &PyEnv, req: &PlanRequest) -> Result;
+
+ /// Install an exact pinned set.
+ ///
+ /// `Batch` mode passes the whole set in one invocation (Phase A); `Isolated` mode is the
+ /// per-package retry loop (Phase B), where a failure must **not** stop the caller's loop.
+ async fn install(
+ &self,
+ env: &PyEnv,
+ specs: &[PinnedSpec],
+ mode: ExecMode,
+ sink: EventSink,
+ ) -> Result;
+
+ /// Remove packages. Always sequential; the reverse-dependency guard runs once up front
+ /// against the full removal set (ARCHITECTURE §8).
+ async fn uninstall(
+ &self,
+ env: &PyEnv,
+ names: &[PkgName],
+ sink: EventSink,
+ ) -> Result;
+
+ /// `pip check` / `uv pip check`, normalized.
+ async fn check(&self, env: &PyEnv) -> Result;
+
+ /// Upgrade pip inside `env`. The uv adapter returns an `Unsupported` error — DATA-FLOW §7
+ /// says pip upkeep is surfaced only when pip is the active engine or present in the env.
+ async fn upgrade_pip(&self, env: &PyEnv) -> Result;
+}
+
+/// pip's floor for `install --dry-run --report -`. Below this, planning is impossible and the app
+/// offers a one-click pip upgrade (`PD-ENG-002`, DATA-FLOW §7).
+pub const PIP_MIN_VERSION_FOR_REPORT: (u32, u32) = (22, 2);
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn documented_pip_floor() {
+ // DATA-FLOW §7 and ERROR-CATALOG PD-ENG-002 both name 22.2; keep them in step.
+ assert_eq!(PIP_MIN_VERSION_FOR_REPORT, (22, 2));
+ }
+}
diff --git a/crates/pipdock-core/src/engine/pip.rs b/crates/pipdock-core/src/engine/pip.rs
new file mode 100644
index 0000000..eff2547
--- /dev/null
+++ b/crates/pipdock-core/src/engine/pip.rs
@@ -0,0 +1,176 @@
+//! The pip adapter: ` -m pip …`.
+//!
+//! Command mapping is fixed by `docs/DATA-FLOW.md` §7. Implementation lands in M1; the argv
+//! builders below are already exercised by tests because they are the surface SECURITY §2 cares
+//! about — nothing else in this file may construct engine arguments.
+
+use async_trait::async_trait;
+
+use crate::errors::Result;
+use crate::model::{
+ CheckReport, Dist, EngineId, EngineInfo, ExecMode, OutdatedDist, PinnedSpec, PkgName, PyEnv,
+ StepResult,
+};
+use crate::plan::{PlanRequest, ResolutionReport};
+
+use super::{Engine, EventSink};
+
+/// Drives pip as a subprocess.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct PipEngine;
+
+impl PipEngine {
+ /// argv for `list --format=json`.
+ #[must_use]
+ pub fn argv_list() -> Vec {
+ vec![
+ "-m".into(),
+ "pip".into(),
+ "list".into(),
+ "--format=json".into(),
+ ]
+ }
+
+ /// argv for `list --outdated --format=json`.
+ #[must_use]
+ pub fn argv_outdated() -> Vec {
+ vec![
+ "-m".into(),
+ "pip".into(),
+ "list".into(),
+ "--outdated".into(),
+ "--format=json".into(),
+ ]
+ }
+
+ /// argv for the dry-run resolve, whose JSON report goes to stdout.
+ #[must_use]
+ pub fn argv_dry_run(specs: &[PinnedSpec]) -> Vec {
+ let mut argv = vec![
+ "-m".into(),
+ "pip".into(),
+ "install".into(),
+ "--dry-run".into(),
+ "--quiet".into(),
+ "--report".into(),
+ "-".into(),
+ ];
+ argv.extend(specs.iter().map(PinnedSpec::to_requirement));
+ argv
+ }
+
+ /// argv for `freeze --all`, used for snapshots. `--all` keeps pip/setuptools in the freeze;
+ /// the snapshot metadata records which engine produced it (DATA-FLOW §7).
+ #[must_use]
+ pub fn argv_freeze() -> Vec {
+ vec!["-m".into(), "pip".into(), "freeze".into(), "--all".into()]
+ }
+
+ /// argv for `check`.
+ #[must_use]
+ pub fn argv_check() -> Vec {
+ vec!["-m".into(), "pip".into(), "check".into()]
+ }
+}
+
+#[async_trait]
+impl Engine for PipEngine {
+ fn id(&self) -> EngineId {
+ EngineId::Pip
+ }
+
+ async fn info(&self, env: &PyEnv) -> EngineInfo {
+ todo!("M1: run `{} -m pip --version`", env.interpreter.display())
+ }
+
+ async fn list_installed(&self, _env: &PyEnv) -> Result> {
+ todo!("M1: parse argv_list() output into Dist")
+ }
+
+ async fn list_outdated(&self, _env: &PyEnv) -> Result> {
+ todo!("M1: parse argv_outdated() output into OutdatedDist")
+ }
+
+ async fn resolve(&self, _env: &PyEnv, _req: &PlanRequest) -> Result {
+ todo!("M1 (SP-2 fixtures): parse `--dry-run --report -` JSON into ResolutionReport")
+ }
+
+ async fn install(
+ &self,
+ _env: &PyEnv,
+ _specs: &[PinnedSpec],
+ _mode: ExecMode,
+ _sink: EventSink,
+ ) -> Result {
+ todo!("M1: two-phase execution per ARCHITECTURE §8")
+ }
+
+ async fn uninstall(
+ &self,
+ _env: &PyEnv,
+ _names: &[PkgName],
+ _sink: EventSink,
+ ) -> Result {
+ todo!("M1: `uninstall -y`, sequential, skip-and-continue")
+ }
+
+ async fn check(&self, _env: &PyEnv) -> Result {
+ todo!("M1: normalize `pip check` findings")
+ }
+
+ async fn upgrade_pip(&self, _env: &PyEnv) -> Result {
+ todo!("M1: `install -U pip`")
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::model::Version;
+
+ #[test]
+ fn dry_run_argv_matches_the_documented_command() {
+ let argv = PipEngine::argv_dry_run(&[]);
+ assert_eq!(
+ argv,
+ [
+ "-m",
+ "pip",
+ "install",
+ "--dry-run",
+ "--quiet",
+ "--report",
+ "-"
+ ]
+ );
+ }
+
+ #[test]
+ fn requirements_are_appended_as_separate_argv_entries() {
+ // One token per argument is what makes shell quoting irrelevant (SECURITY §2).
+ let specs = [
+ PinnedSpec {
+ name: PkgName::parse("httpx").unwrap(),
+ version: Version("0.28.1".into()),
+ },
+ PinnedSpec {
+ name: PkgName::parse("Requests").unwrap(),
+ version: Version("2.32.3".into()),
+ },
+ ];
+ let argv = PipEngine::argv_dry_run(&specs);
+ assert_eq!(
+ &argv[argv.len() - 2..],
+ ["httpx==0.28.1", "requests==2.32.3"]
+ );
+ assert!(
+ argv.iter().all(|a| !a.contains(' ')),
+ "no argv entry may bundle multiple arguments"
+ );
+ }
+
+ #[test]
+ fn freeze_uses_all_so_snapshots_include_pip_itself() {
+ assert!(PipEngine::argv_freeze().contains(&"--all".to_string()));
+ }
+}
diff --git a/crates/pipdock-core/src/engine/uv.rs b/crates/pipdock-core/src/engine/uv.rs
new file mode 100644
index 0000000..d55dfdd
--- /dev/null
+++ b/crates/pipdock-core/src/engine/uv.rs
@@ -0,0 +1,167 @@
+//! The uv adapter: `uv pip … --python `.
+//!
+//! **This adapter is gated on spike SP-1.** Unlike pip, uv has no stable JSON report for
+//! `install --dry-run` — it prints a text plan. SP-1 must establish whether that text carries
+//! enough information to populate [`ResolutionReport::held_back`] blockers; if it does not,
+//! `docs/ROADMAP.md` says v1.0 ships pip-primary with uv behind a beta-engine flag.
+//!
+//! Until SP-1 lands, the parsing entry point below is deliberately unimplemented rather than
+//! guessed at, and `PD-ENG-003` is the documented outcome when uv emits a shape the adapter does
+//! not recognize.
+
+use async_trait::async_trait;
+
+use crate::errors::Result;
+use crate::model::{
+ CheckReport, Dist, EngineId, EngineInfo, ExecMode, OutdatedDist, PinnedSpec, PkgName, PyEnv,
+ StepResult,
+};
+use crate::plan::{PlanRequest, ResolutionReport};
+
+use super::{Engine, EventSink};
+
+/// Drives uv as a subprocess.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct UvEngine;
+
+impl UvEngine {
+ /// argv for `uv pip list --format=json --python `.
+ #[must_use]
+ pub fn argv_list(python: &str) -> Vec {
+ vec![
+ "pip".into(),
+ "list".into(),
+ "--format=json".into(),
+ "--python".into(),
+ python.into(),
+ ]
+ }
+
+ /// argv for `uv pip install -U --dry-run --python [specs…]`.
+ #[must_use]
+ pub fn argv_dry_run(python: &str, specs: &[PinnedSpec]) -> Vec {
+ let mut argv = vec![
+ "pip".into(),
+ "install".into(),
+ "-U".into(),
+ "--dry-run".into(),
+ "--python".into(),
+ python.into(),
+ ];
+ argv.extend(specs.iter().map(PinnedSpec::to_requirement));
+ argv
+ }
+
+ /// argv for `uv pip freeze --python `. Note uv has no `--all`, so snapshots taken with
+ /// the uv engine omit pip/setuptools — the snapshot metadata records the engine for this
+ /// reason (DATA-FLOW §7).
+ #[must_use]
+ pub fn argv_freeze(python: &str) -> Vec {
+ vec![
+ "pip".into(),
+ "freeze".into(),
+ "--python".into(),
+ python.into(),
+ ]
+ }
+
+ /// Parse uv's text dry-run plan into the normalized report.
+ ///
+ /// # Errors
+ /// Returns `PD-ENG-003` when the output does not match any shape the adapter knows.
+ pub fn parse_dry_run(_stdout: &str) -> Result {
+ todo!("SP-1: pin uv's text plan format against captured fixtures before parsing it")
+ }
+}
+
+#[async_trait]
+impl Engine for UvEngine {
+ fn id(&self) -> EngineId {
+ EngineId::Uv
+ }
+
+ async fn info(&self, _env: &PyEnv) -> EngineInfo {
+ todo!("M1: run `uv --version`")
+ }
+
+ async fn list_installed(&self, _env: &PyEnv) -> Result> {
+ todo!("M1: normalize uv's list output into Dist (shape differs slightly from pip)")
+ }
+
+ async fn list_outdated(&self, _env: &PyEnv) -> Result> {
+ todo!("M1 (SP-1 fixtures): parse uv's outdated output")
+ }
+
+ async fn resolve(&self, _env: &PyEnv, _req: &PlanRequest) -> Result {
+ todo!("SP-1 go/no-go gates this")
+ }
+
+ async fn install(
+ &self,
+ _env: &PyEnv,
+ _specs: &[PinnedSpec],
+ _mode: ExecMode,
+ _sink: EventSink,
+ ) -> Result {
+ todo!("M1: two-phase execution per ARCHITECTURE §8")
+ }
+
+ async fn uninstall(
+ &self,
+ _env: &PyEnv,
+ _names: &[PkgName],
+ _sink: EventSink,
+ ) -> Result {
+ todo!("M1: `uv pip uninstall`, sequential, skip-and-continue")
+ }
+
+ async fn check(&self, _env: &PyEnv) -> Result {
+ todo!("M1: normalize `uv pip check` findings")
+ }
+
+ async fn upgrade_pip(&self, _env: &PyEnv) -> Result {
+ // Documented behaviour, not a gap: pip upkeep is a pip-engine concern (DATA-FLOW §7).
+ Err(crate::errors::PdError::new(
+ crate::errors::Code::EngNotFound,
+ "pip upkeep is not available while uv is the active engine",
+ ))
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ const PY: &str = r"C:\proj\.venv\Scripts\python.exe";
+
+ #[test]
+ fn dry_run_argv_targets_the_selected_interpreter() {
+ let argv = UvEngine::argv_dry_run(PY, &[]);
+ assert_eq!(argv, ["pip", "install", "-U", "--dry-run", "--python", PY]);
+ }
+
+ #[test]
+ fn a_windows_path_stays_one_argv_entry() {
+ // The path contains backslashes and could contain spaces; because it is its own argv
+ // entry there is nothing to quote or escape (SECURITY §2).
+ let argv = UvEngine::argv_freeze(r"C:\Program Files\Python312\python.exe");
+ assert_eq!(argv.len(), 4);
+ assert_eq!(argv[3], r"C:\Program Files\Python312\python.exe");
+ }
+
+ #[tokio::test]
+ async fn upgrade_pip_is_refused_with_a_catalog_code() {
+ let env = PyEnv {
+ interpreter: PY.into(),
+ prefix: r"C:\proj\.venv".into(),
+ python_version: "3.12.4".into(),
+ externally_managed: false,
+ source: crate::model::EnvSource::VenvScan,
+ };
+ let err = UvEngine
+ .upgrade_pip(&env)
+ .await
+ .expect_err("uv cannot upgrade pip");
+ assert_eq!(err.code, crate::errors::Code::EngNotFound);
+ }
+}
diff --git a/crates/pipdock-core/src/envs/mod.rs b/crates/pipdock-core/src/envs/mod.rs
new file mode 100644
index 0000000..9d467eb
--- /dev/null
+++ b/crates/pipdock-core/src/envs/mod.rs
@@ -0,0 +1,52 @@
+//! Environment discovery and probing. See ARCHITECTURE §4 and DATA-FLOW §2.
+//!
+//! Discovery sources, in the order the Environments screen shows them (PRD P0-1):
+//! PEP 514 registry, the `py` launcher (`py -0p`), `uv python list`, known venv directories,
+//! and manual *Browse…*. Spike SP-6 sweeps all of these on a real machine, including the
+//! Microsoft Store Python aliasing quirks, before this module is written.
+
+use crate::errors::Result;
+use crate::model::PyEnv;
+
+/// The embedded introspection helper, executed as ` -I probe.py --json`.
+///
+/// SECURITY §2: `-I` (isolated mode) makes the probe ignore `PYTHONPATH` and user site, so a
+/// poisoned environment cannot inject code into it. It is written to a temp file with a random
+/// name per invocation and is **never** installed into the environment.
+pub const PROBE_PY: &str = include_str!("../probe.py");
+
+/// Lowest Python the probe supports; it uses `importlib.metadata` only (ARCHITECTURE §4).
+pub const MIN_PROBE_PYTHON: (u32, u32) = (3, 10);
+
+/// Discover every environment on this machine.
+///
+/// # Errors
+/// Returns a `PD-ENV-*` code when a discovery source fails in a way the user must act on.
+pub fn scan() -> Result> {
+ todo!("M1, after SP-6: PEP 514 registry + py -0p + uv python list + venv scan")
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn probe_is_embedded_and_stdlib_only() {
+ assert!(
+ PROBE_PY.contains("importlib.metadata"),
+ "probe must read metadata"
+ );
+ // ARCHITECTURE §4: no third-party imports. These are the ones a careless edit would add.
+ for forbidden in [
+ "import requests",
+ "import packaging",
+ "import setuptools",
+ "import pip",
+ ] {
+ assert!(
+ !PROBE_PY.contains(forbidden),
+ "probe must stay stdlib-only: {forbidden}"
+ );
+ }
+ }
+}
diff --git a/crates/pipdock-core/src/errors/catalog.rs b/crates/pipdock-core/src/errors/catalog.rs
new file mode 100644
index 0000000..b69e88d
--- /dev/null
+++ b/crates/pipdock-core/src/errors/catalog.rs
@@ -0,0 +1,303 @@
+//! The error catalog: the single source of truth for every user-visible failure.
+//!
+//! Mirrors `docs/ERROR-CATALOG.md` §2. Two rules from that document are structural:
+//!
+//! 1. Every user-visible failure carries **exactly one** code.
+//! 2. Classifiers run over engine stderr in **priority order, first match wins**, falling back to
+//! [`Code::EngUnclassified`] (`PD-ENG-999`).
+//!
+//! Codes and stderr are never localized — only the one-liner and action text are, and those live
+//! in the i18next catalogs (`docs/I18N.md` §1). The `as_str` values below are the i18next keys'
+//! discriminators, so they must stay stable once shipped.
+
+use std::fmt;
+
+/// Catalog area: the `` in `PD--`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "UPPERCASE")]
+pub enum Area {
+ /// Environment discovery, probing, PEP 668.
+ Env,
+ /// Engine availability and output shape.
+ Eng,
+ /// Dependency resolution.
+ Res,
+ /// Build backends and compiled extensions.
+ Bld,
+ /// Package identity and the index.
+ Pkg,
+ /// Network and TLS.
+ Net,
+ /// Filesystem permissions and locks.
+ Prm,
+ /// Snapshots and rollback.
+ Snp,
+ /// Host system limits.
+ Sys,
+ /// Code Health tooling.
+ Hlt,
+ /// PipDock's own bugs.
+ Int,
+}
+
+/// Every code PipDock can surface at v1 launch.
+///
+/// `docs/TESTING.md` §2 requires at least one captured stderr fixture per variant before ship;
+/// the test that enforces "no code without fixture" lives beside the classifiers.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+#[non_exhaustive]
+pub enum Code {
+ // -- PD-ENV: environment ------------------------------------------------
+ /// Interpreter path missing or not executable — the env was deleted or moved.
+ EnvInterpreterMissing,
+ /// PEP 668 `EXTERNALLY-MANAGED` marker present; mutation blocked by default.
+ EnvExternallyManaged,
+ /// `probe.py` exited non-zero or produced unparseable output.
+ EnvProbeFailed,
+
+ // -- PD-ENG: engine -----------------------------------------------------
+ /// pip or uv binary not found.
+ EngNotFound,
+ /// pip older than 22.2, which predates `--dry-run --report`.
+ EngPipTooOld,
+ /// uv emitted a shape the adapter does not recognize (uv newer than PipDock).
+ EngUvShapeUnknown,
+ /// Fallback for engine failures no classifier matched. Always last.
+ EngUnclassified,
+
+ // -- PD-RES: resolution -------------------------------------------------
+ /// `ResolutionImpossible` or the uv equivalent: constraints cannot be satisfied.
+ ResImpossible,
+ /// Plan older than 10 minutes, or the env's probe hash changed since the preview.
+ ResPlanStale,
+
+ // -- PD-BLD: build ------------------------------------------------------
+ /// MSVC build tools required but absent.
+ BldMsvcMissing,
+ /// Build backend failed (`pyproject.toml` error, `metadata-generation-failed`).
+ BldBackendFailed,
+ /// Generic sdist wheel-build failure.
+ BldWheelFailed,
+
+ // -- PD-PKG: package & index -------------------------------------------
+ /// No matching distribution, and metadata shows a requires-python mismatch.
+ PkgRequiresPython,
+ /// No matching distribution: name or version typo, or the release is gone.
+ PkgNotFound,
+ /// The requested release was yanked.
+ PkgYanked,
+ /// Downloaded artifact failed hash verification.
+ PkgHashMismatch,
+
+ // -- PD-NET: network ----------------------------------------------------
+ /// Timeout, connection aborted, or DNS failure.
+ NetUnreachable,
+ /// TLS/SSL verification failed — typically proxy or AV interception.
+ NetTlsFailure,
+ /// PEP 691 index refresh failed; the stale index stays searchable.
+ NetIndexRefreshFailed,
+ /// Code Health tools-venv bootstrap could not reach PyPI.
+ NetToolsBootstrapFailed,
+
+ // -- PD-PRM: permissions ------------------------------------------------
+ /// `PermissionError` writing site-packages (admin-owned Python).
+ PrmSitePackagesReadOnly,
+ /// File locked by a running process (`WinError 32`).
+ PrmFileLocked,
+
+ // -- PD-SNP: snapshot ---------------------------------------------------
+ /// Snapshot write failed before execution. **The plan is aborted; nothing runs.**
+ SnpWriteFailed,
+ /// A release needed to restore a snapshot is no longer available on PyPI.
+ SnpTargetUnavailable,
+
+ // -- PD-SYS: system -----------------------------------------------------
+ /// `MAX_PATH` exceeded without the long-path opt-in.
+ SysPathTooLong,
+ /// Disk full.
+ SysDiskFull,
+
+ // -- PD-HLT: code health ------------------------------------------------
+ /// A Code Health tool is missing from the tools venv.
+ HltToolMissing,
+ /// A Code Health tool exited non-zero.
+ HltToolFailed,
+ /// A Code Health tool exceeded its watchdog timeout; partial report shown.
+ HltTimeout,
+
+ // -- PD-INT: internal ---------------------------------------------------
+ /// A PipDock bug: panic or unexpected state.
+ IntUnexpected,
+}
+
+impl Code {
+ /// The wire form, e.g. `"PD-BLD-002"`. Stable once shipped: it appears in logs, in `--json`
+ /// output, and in prefilled bug-report URLs.
+ #[must_use]
+ pub const fn as_str(self) -> &'static str {
+ match self {
+ Self::EnvInterpreterMissing => "PD-ENV-001",
+ Self::EnvExternallyManaged => "PD-ENV-002",
+ Self::EnvProbeFailed => "PD-ENV-003",
+ Self::EngNotFound => "PD-ENG-001",
+ Self::EngPipTooOld => "PD-ENG-002",
+ Self::EngUvShapeUnknown => "PD-ENG-003",
+ Self::EngUnclassified => "PD-ENG-999",
+ Self::ResImpossible => "PD-RES-001",
+ Self::ResPlanStale => "PD-RES-002",
+ Self::BldMsvcMissing => "PD-BLD-001",
+ Self::BldBackendFailed => "PD-BLD-002",
+ Self::BldWheelFailed => "PD-BLD-003",
+ Self::PkgRequiresPython => "PD-PKG-001",
+ Self::PkgNotFound => "PD-PKG-002",
+ Self::PkgYanked => "PD-PKG-003",
+ Self::PkgHashMismatch => "PD-PKG-004",
+ Self::NetUnreachable => "PD-NET-001",
+ Self::NetTlsFailure => "PD-NET-002",
+ Self::NetIndexRefreshFailed => "PD-NET-010",
+ Self::NetToolsBootstrapFailed => "PD-NET-011",
+ Self::PrmSitePackagesReadOnly => "PD-PRM-001",
+ Self::PrmFileLocked => "PD-PRM-002",
+ Self::SnpWriteFailed => "PD-SNP-001",
+ Self::SnpTargetUnavailable => "PD-SNP-002",
+ Self::SysPathTooLong => "PD-SYS-001",
+ Self::SysDiskFull => "PD-SYS-002",
+ Self::HltToolMissing => "PD-HLT-001",
+ Self::HltToolFailed => "PD-HLT-002",
+ Self::HltTimeout => "PD-HLT-003",
+ Self::IntUnexpected => "PD-INT-001",
+ }
+ }
+
+ /// The catalog area this code belongs to.
+ #[must_use]
+ pub const fn area(self) -> Area {
+ match self {
+ Self::EnvInterpreterMissing | Self::EnvExternallyManaged | Self::EnvProbeFailed => {
+ Area::Env
+ }
+ Self::EngNotFound
+ | Self::EngPipTooOld
+ | Self::EngUvShapeUnknown
+ | Self::EngUnclassified => Area::Eng,
+ Self::ResImpossible | Self::ResPlanStale => Area::Res,
+ Self::BldMsvcMissing | Self::BldBackendFailed | Self::BldWheelFailed => Area::Bld,
+ Self::PkgRequiresPython
+ | Self::PkgNotFound
+ | Self::PkgYanked
+ | Self::PkgHashMismatch => Area::Pkg,
+ Self::NetUnreachable
+ | Self::NetTlsFailure
+ | Self::NetIndexRefreshFailed
+ | Self::NetToolsBootstrapFailed => Area::Net,
+ Self::PrmSitePackagesReadOnly | Self::PrmFileLocked => Area::Prm,
+ Self::SnpWriteFailed | Self::SnpTargetUnavailable => Area::Snp,
+ Self::SysPathTooLong | Self::SysDiskFull => Area::Sys,
+ Self::HltToolMissing | Self::HltToolFailed | Self::HltTimeout => Area::Hlt,
+ Self::IntUnexpected => Area::Int,
+ }
+ }
+
+ /// Every code, in catalog order. The fixture-coverage test in `docs/TESTING.md` §2 iterates
+ /// this, so a new variant fails CI until it has a captured stderr fixture.
+ pub const ALL: &'static [Self] = &[
+ Self::EnvInterpreterMissing,
+ Self::EnvExternallyManaged,
+ Self::EnvProbeFailed,
+ Self::EngNotFound,
+ Self::EngPipTooOld,
+ Self::EngUvShapeUnknown,
+ Self::ResImpossible,
+ Self::ResPlanStale,
+ Self::BldMsvcMissing,
+ Self::BldBackendFailed,
+ Self::BldWheelFailed,
+ Self::PkgRequiresPython,
+ Self::PkgNotFound,
+ Self::PkgYanked,
+ Self::PkgHashMismatch,
+ Self::NetUnreachable,
+ Self::NetTlsFailure,
+ Self::NetIndexRefreshFailed,
+ Self::NetToolsBootstrapFailed,
+ Self::PrmSitePackagesReadOnly,
+ Self::PrmFileLocked,
+ Self::SnpWriteFailed,
+ Self::SnpTargetUnavailable,
+ Self::SysPathTooLong,
+ Self::SysDiskFull,
+ Self::HltToolMissing,
+ Self::HltToolFailed,
+ Self::HltTimeout,
+ Self::IntUnexpected,
+ Self::EngUnclassified,
+ ];
+}
+
+impl fmt::Display for Code {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.write_str(self.as_str())
+ }
+}
+
+/// Classify an engine's stderr into a catalog code.
+///
+/// Filled during spike SP-2, which captures real stderr for each case. Until then this returns
+/// the documented fallback so no call site can accidentally surface an uncoded failure.
+///
+/// Contract when implemented: patterns are checked in priority order and the **first** match wins.
+#[must_use]
+pub fn classify_stderr(_stderr: &str) -> Code {
+ Code::EngUnclassified
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::collections::HashSet;
+
+ #[test]
+ fn every_variant_is_listed_in_all() {
+ // `ALL` drives the fixture-coverage gate, so a variant missing from it would silently
+ // escape that gate. There is no derive for "enumerate variants", hence this count check.
+ assert_eq!(Code::ALL.len(), 30, "add the new variant to Code::ALL");
+ }
+
+ #[test]
+ fn wire_codes_are_unique() {
+ let seen: HashSet<&str> = Code::ALL.iter().map(|c| c.as_str()).collect();
+ assert_eq!(
+ seen.len(),
+ Code::ALL.len(),
+ "duplicate wire code in catalog"
+ );
+ }
+
+ #[test]
+ fn wire_codes_match_the_documented_grammar() {
+ for code in Code::ALL {
+ let s = code.as_str();
+ let mut parts = s.split('-');
+ assert_eq!(parts.next(), Some("PD"), "{s} must start with PD");
+ let area = parts.next().unwrap_or_default();
+ let num = parts.next().unwrap_or_default();
+ assert_eq!(parts.next(), None, "{s} has too many segments");
+ assert_eq!(area.len(), 3, "{s} area must be 3 letters");
+ assert!(
+ area.chars().all(|c| c.is_ascii_uppercase()),
+ "{s} area case"
+ );
+ assert_eq!(num.len(), 3, "{s} number must be 3 digits");
+ assert!(num.chars().all(|c| c.is_ascii_digit()), "{s} number digits");
+ }
+ }
+
+ #[test]
+ fn unclassified_is_the_documented_fallback() {
+ assert_eq!(
+ classify_stderr("something nobody has seen before"),
+ Code::EngUnclassified
+ );
+ assert_eq!(Code::EngUnclassified.as_str(), "PD-ENG-999");
+ }
+}
diff --git a/crates/pipdock-core/src/errors/mod.rs b/crates/pipdock-core/src/errors/mod.rs
new file mode 100644
index 0000000..30a07a4
--- /dev/null
+++ b/crates/pipdock-core/src/errors/mod.rs
@@ -0,0 +1,104 @@
+//! Error types. See `docs/ERROR-CATALOG.md`.
+
+pub mod catalog;
+
+pub use catalog::{Area, Code, classify_stderr};
+
+/// The error type crossing every boundary: Tauri IPC, CLI output, logs.
+///
+/// Invariant 4 of `docs/DATA-FLOW.md` §9: every failure surfaced to UI or CLI carries a catalog
+/// code. That is why `code` is not optional.
+#[derive(Debug, thiserror::Error, serde::Serialize, serde::Deserialize)]
+#[error("error[{code}]: {message}")]
+pub struct PdError {
+ /// The single catalog code for this failure.
+ pub code: Code,
+ /// Developer-facing detail. **Not** the user-facing string — per `docs/I18N.md` §1 the core
+ /// emits codes and structured data only; the localized one-liner is looked up frontend-side
+ /// from the code.
+ pub message: String,
+ /// Tail of the engine's stderr, capped at the 40 lines `docs/ERROR-CATALOG.md` §3 shows.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub stderr_tail: Option,
+}
+
+impl PdError {
+ /// Build an error for `code` with developer-facing detail.
+ #[must_use]
+ pub fn new(code: Code, message: impl Into) -> Self {
+ Self {
+ code,
+ message: message.into(),
+ stderr_tail: None,
+ }
+ }
+
+ /// Attach an engine stderr tail, truncated to the last `MAX_STDERR_TAIL_LINES` lines.
+ #[must_use]
+ pub fn with_stderr(mut self, stderr: impl AsRef) -> Self {
+ let stderr = stderr.as_ref();
+ let tail: Vec<&str> = stderr
+ .lines()
+ .rev()
+ .take(MAX_STDERR_TAIL_LINES)
+ .collect::>()
+ .into_iter()
+ .rev()
+ .collect();
+ self.stderr_tail = Some(tail.join("\n"));
+ self
+ }
+
+ /// Classify an engine failure from its stderr (SP-2 fills the classifier table).
+ #[must_use]
+ pub fn from_engine_stderr(stderr: impl AsRef) -> Self {
+ let stderr = stderr.as_ref();
+ Self::new(classify_stderr(stderr), "engine command failed").with_stderr(stderr)
+ }
+}
+
+/// `docs/ERROR-CATALOG.md` §3: the GUI's *Details* pane shows at most this many stderr lines.
+pub const MAX_STDERR_TAIL_LINES: usize = 40;
+
+/// Convenience alias for core results.
+pub type Result = std::result::Result;
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn stderr_tail_keeps_the_last_lines_in_order() {
+ let stderr = (1..=60)
+ .map(|n| n.to_string())
+ .collect::>()
+ .join("\n");
+ let err = PdError::new(Code::BldBackendFailed, "boom").with_stderr(&stderr);
+ let tail = err.stderr_tail.unwrap_or_default();
+ let lines: Vec<&str> = tail.lines().collect();
+
+ assert_eq!(lines.len(), MAX_STDERR_TAIL_LINES);
+ assert_eq!(
+ lines.first(),
+ Some(&"21"),
+ "should start 40 lines from the end"
+ );
+ assert_eq!(
+ lines.last(),
+ Some(&"60"),
+ "should keep the newest line last"
+ );
+ }
+
+ #[test]
+ fn short_stderr_is_kept_whole() {
+ let err = PdError::new(Code::BldBackendFailed, "boom").with_stderr("a\nb");
+ assert_eq!(err.stderr_tail.as_deref(), Some("a\nb"));
+ }
+
+ #[test]
+ fn display_leads_with_the_code() {
+ let err = PdError::new(Code::SnpWriteFailed, "disk full");
+ assert_eq!(err.to_string(), "error[PD-SNP-001]: disk full");
+ }
+}
diff --git a/crates/pipdock-core/src/graph/mod.rs b/crates/pipdock-core/src/graph/mod.rs
new file mode 100644
index 0000000..7456991
--- /dev/null
+++ b/crates/pipdock-core/src/graph/mod.rs
@@ -0,0 +1,31 @@
+//! The reverse-dependency graph, built from `probe.py`'s `requires_dist` data.
+//!
+//! Three features read it (ARCHITECTURE §4): held-back blocker attribution, the uninstall guard,
+//! and pin auto-suggest. `docs/TESTING.md` §1 lists its correctness as something that must never
+//! regress, including cycles and `pkg[extra]` markers.
+
+use crate::model::{Dist, PkgName};
+
+/// Who depends on what, keyed by the depended-upon package.
+#[derive(Debug, Default)]
+pub struct ReverseDeps;
+
+impl ReverseDeps {
+ /// Build the graph from a full environment listing.
+ #[must_use]
+ pub fn build(_dists: &[Dist]) -> Self {
+ todo!("M1: parse requires_dist, honour extras and environment markers")
+ }
+
+ /// Packages that would break if `pkg` were removed.
+ ///
+ /// This is the uninstall guard's whole job: bare `pip uninstall` performs no dependency check
+ /// at all (DATA-FLOW §5).
+ #[must_use]
+ pub fn dependents_of(&self, _pkg: &PkgName) -> Vec {
+ todo!("M1: reverse lookup")
+ }
+}
+
+/// PRD P1-2: default reverse-dependency count at which a pin is suggested. Configurable.
+pub const PIN_SUGGEST_THRESHOLD: usize = 5;
diff --git a/crates/pipdock-core/src/health/mod.rs b/crates/pipdock-core/src/health/mod.rs
new file mode 100644
index 0000000..92fad61
--- /dev/null
+++ b/crates/pipdock-core/src/health/mod.rs
@@ -0,0 +1,25 @@
+//! Code Health: deptry, vulture and ruff run from PipDock's own isolated tools venv.
+//!
+//! See `docs/CODE-HEALTH-SPEC.md`. Two boundaries are contractual (§1, §7): deptry and vulture are
+//! **report-only**, and the sole write path is `ruff --fix` / `ruff format` behind an explicit
+//! confirm. PipDock never edits `pyproject.toml` or `requirements.txt` for the user.
+
+use crate::errors::Result;
+
+/// CODE-HEALTH-SPEC §4: per-tool watchdog; exceeding it yields a partial report (`PD-HLT-003`).
+pub const TOOL_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(120);
+
+/// CODE-HEALTH-SPEC §4: vulture's default confidence floor.
+pub const DEFAULT_MIN_CONFIDENCE: u8 = 80;
+
+/// CODE-HEALTH-SPEC §4: directories excluded from every tool, plus user globs from Settings.
+pub const DEFAULT_EXCLUDES: &[&str] = &[".venv", "venv", "node_modules", "build", "dist", ".git"];
+
+/// Create or re-sync the tools venv from the shipped `tools-requirements.txt`.
+///
+/// # Errors
+/// Returns `PD-NET-011` when bootstrap cannot reach PyPI; Health stays disabled and every other
+/// tab is unaffected (CODE-HEALTH-SPEC §2).
+pub fn sync_tools_venv() -> Result<()> {
+ todo!(r"M3: create %LOCALAPPDATA%\PipDock\tools\.venv from exact pins")
+}
diff --git a/crates/pipdock-core/src/index/mod.rs b/crates/pipdock-core/src/index/mod.rs
new file mode 100644
index 0000000..2b75172
--- /dev/null
+++ b/crates/pipdock-core/src/index/mod.rs
@@ -0,0 +1,28 @@
+//! PyPI name index and metadata cache. See ARCHITECTURE §5.
+//!
+//! The PEP 691 JSON Simple Index is ingested into SQLite (`index.db`, table `names`), and fuzzy
+//! search runs in Rust over the normalized column. Spike SP-3 measures whether the documented
+//! budgets hold on ~600 k project names before this module is written.
+
+use crate::errors::Result;
+use crate::model::PkgName;
+
+/// UI-SPEC §4 and PRD §6: keystroke-to-results budget for the local index.
+pub const SEARCH_LATENCY_BUDGET: std::time::Duration = std::time::Duration::from_millis(50);
+
+/// ROADMAP SP-3: cold refresh of the full name index must finish inside this.
+pub const COLD_REFRESH_BUDGET: std::time::Duration = std::time::Duration::from_secs(60);
+
+/// ARCHITECTURE §5: the name index is refreshed manually or on this cadence.
+pub const INDEX_REFRESH_INTERVAL_DAYS: u32 = 7;
+
+/// ARCHITECTURE §5: per-package PyPI JSON metadata is cached this long.
+pub const METADATA_TTL_HOURS: u32 = 24;
+
+/// Fuzzy-search the cached name index.
+///
+/// # Errors
+/// Returns `PD-NET-010` when the index has never been populated.
+pub fn search(_query: &str, _limit: usize) -> Result> {
+ todo!("M1, after SP-3: nucleo matcher over the normalized names column")
+}
diff --git a/crates/pipdock-core/src/lib.rs b/crates/pipdock-core/src/lib.rs
new file mode 100644
index 0000000..da9bddd
--- /dev/null
+++ b/crates/pipdock-core/src/lib.rs
@@ -0,0 +1,52 @@
+//! PipDock's domain logic — **this crate is the product**.
+//!
+//! The Tauri GUI (`src-tauri`) and the clap CLI (`pipdock-cli`) are thin adapters over these
+//! functions; neither contains business logic (ARCHITECTURE §1.1). Read `docs/ARCHITECTURE.md`
+//! before changing anything here.
+//!
+//! # Invariants this crate enforces
+//!
+//! From `docs/DATA-FLOW.md` §9, tested rather than assumed:
+//!
+//! 1. No mutating engine call without a [`plan::ResolutionReport`] accepted in this session.
+//! 2. No mutating engine call without a successful snapshot write.
+//! 3. `plan_execute` refuses a report older than [`plan::PLAN_MAX_AGE`], or one whose environment
+//! probe hash has changed.
+//! 4. Every failure surfaced to the UI or CLI carries an [`errors::Code`].
+//! 5. Pinned packages never enter `PlanRequest::upgrades` unless explicitly unpinned this session.
+//!
+//! # Status
+//!
+//! Phase 0. Types and command surfaces are defined; behaviour lands in M1, gated on the spikes in
+//! `docs/ROADMAP.md`. In particular [`engine::uv`] is gated on SP-1, which decides whether v1.0
+//! ships both engines.
+
+#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
+
+pub mod engine;
+pub mod envs;
+pub mod errors;
+pub mod graph;
+pub mod health;
+pub mod index;
+pub mod model;
+pub mod pins;
+pub mod plan;
+pub mod snapshot;
+
+pub use errors::{Code, PdError, Result};
+pub use model::{Dist, EngineId, OutdatedDist, PkgName, PyEnv, Version};
+
+/// The application data directory under `%LOCALAPPDATA%` (ARCHITECTURE §6).
+pub const APP_DATA_DIR_NAME: &str = "PipDock";
+
+/// Log retention in `%LOCALAPPDATA%\PipDock\logs\` (ARCHITECTURE §6).
+pub const LOG_RETENTION_DAYS: u32 = 14;
+
+/// Size of the per-plan engine output ring buffer that backs *Report bug*
+/// (`docs/ERROR-CATALOG.md` §4).
+pub const LOG_RING_BUFFER_BYTES: usize = 64 * 1024;
+
+/// `docs/ERROR-CATALOG.md` §4.3: GitHub rejects very long URLs, so the prefilled `log-excerpt`
+/// is truncated (tail-biased) to this many characters. The full log goes to the clipboard.
+pub const BUG_REPORT_EXCERPT_CHARS: usize = 6_000;
diff --git a/crates/pipdock-core/src/model.rs b/crates/pipdock-core/src/model.rs
new file mode 100644
index 0000000..bf390af
--- /dev/null
+++ b/crates/pipdock-core/src/model.rs
@@ -0,0 +1,328 @@
+//! Core domain types shared by every module, the CLI and the GUI.
+//!
+//! These are the types `specta`/`tauri-specta` will export to TypeScript (ARCHITECTURE §9), so
+//! their serde representation is part of the public contract — see `docs/CLI-SPEC.md` §6.
+
+use std::path::PathBuf;
+
+use crate::errors::{Code, PdError, Result};
+
+/// Which resolver PipDock is driving.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum EngineId {
+ /// ` -m pip …`
+ Pip,
+ /// `uv pip … --python `
+ Uv,
+}
+
+impl EngineId {
+ /// Wire form, also what the status-line engine badge shows (UI-SPEC §3).
+ #[must_use]
+ pub const fn as_str(self) -> &'static str {
+ match self {
+ Self::Pip => "pip",
+ Self::Uv => "uv",
+ }
+ }
+}
+
+/// Availability and version of an engine for a given environment.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct EngineInfo {
+ /// Which engine this describes.
+ pub id: EngineId,
+ /// Reported version, absent when the engine is not available.
+ pub version: Option,
+ /// False means the binary or module could not be found (`PD-ENG-001`).
+ pub available: bool,
+}
+
+/// How an environment was discovered. Surfaced as the source chip in the Environments screen.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EnvSource {
+ /// PEP 514 registry entry.
+ Registry,
+ /// Reported by the `py` launcher (`py -0p`).
+ PyLauncher,
+ /// Reported by `uv python list`.
+ Uv,
+ /// Found by scanning known venv directories.
+ VenvScan,
+ /// Added by the user via *Browse…*.
+ Manual,
+}
+
+/// A Python environment PipDock can act on.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct PyEnv {
+ /// Canonicalized path to the interpreter. Never a shell string — see SECURITY §2.
+ pub interpreter: PathBuf,
+ /// `sys.prefix` as reported by `probe.py`.
+ pub prefix: PathBuf,
+ /// e.g. `"3.12.4"`.
+ pub python_version: String,
+ /// PEP 668 marker present. When true, mutation is blocked unless the user enabled the
+ /// Settings override (`PD-ENV-002`, SECURITY §3).
+ pub externally_managed: bool,
+ /// Where this env came from.
+ pub source: EnvSource,
+}
+
+/// A PEP 503-normalized distribution name.
+///
+/// Constructing one is the *only* way a package name reaches an argv array, which is what makes
+/// SECURITY §2's "validated before it reaches argv" claim structural rather than aspirational.
+#[derive(
+ Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Serialize, serde::Deserialize,
+)]
+#[serde(transparent)]
+pub struct PkgName(String);
+
+impl PkgName {
+ /// Validate and normalize a distribution name.
+ ///
+ /// Accepts the PEP 508 name grammar — `^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$` — then
+ /// applies PEP 503 normalization: lowercase, and runs of `-`, `_` or `.` collapse to a single
+ /// `-`. Anything else is rejected with `PD-PKG-002`.
+ ///
+ /// # Errors
+ /// Returns `PD-PKG-002` when `raw` is not a valid distribution name.
+ pub fn parse(raw: &str) -> Result {
+ let invalid = || PdError::new(Code::PkgNotFound, format!("invalid package name: {raw:?}"));
+
+ if raw.is_empty() {
+ return Err(invalid());
+ }
+ let bytes = raw.as_bytes();
+ let alnum = |b: u8| b.is_ascii_alphanumeric();
+ // First and last characters must be alphanumeric; the middle may also use . _ -
+ if !alnum(bytes[0]) || !alnum(bytes[bytes.len() - 1]) {
+ return Err(invalid());
+ }
+ if !bytes
+ .iter()
+ .all(|&b| alnum(b) || matches!(b, b'.' | b'_' | b'-'))
+ {
+ return Err(invalid());
+ }
+
+ // PEP 503 normalization.
+ let mut out = String::with_capacity(raw.len());
+ let mut prev_was_separator = false;
+ for ch in raw.chars() {
+ if matches!(ch, '.' | '_' | '-') {
+ if !prev_was_separator {
+ out.push('-');
+ }
+ prev_was_separator = true;
+ } else {
+ out.push(ch.to_ascii_lowercase());
+ prev_was_separator = false;
+ }
+ }
+ Ok(Self(out))
+ }
+
+ /// The normalized name.
+ #[must_use]
+ pub fn as_str(&self) -> &str {
+ &self.0
+ }
+}
+
+impl std::fmt::Display for PkgName {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.write_str(&self.0)
+ }
+}
+
+/// A version string as the engine reported it. Never reshaped or localized (I18N §2).
+#[derive(Debug, Clone, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+#[serde(transparent)]
+pub struct Version(pub String);
+
+impl std::fmt::Display for Version {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.write_str(&self.0)
+ }
+}
+
+/// What the user asked for: a name, optionally constrained.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct Spec {
+ /// Normalized distribution name.
+ pub name: PkgName,
+ /// PEP 440 specifier such as `">=2,<3"`, or `None` for "latest".
+ pub version_req: Option,
+}
+
+/// A resolved, exact `name==version` pair. Only these reach a mutating engine command.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct PinnedSpec {
+ /// Normalized distribution name.
+ pub name: PkgName,
+ /// The exact version the resolver chose.
+ pub version: Version,
+}
+
+impl PinnedSpec {
+ /// Render as the `name==version` argv token.
+ #[must_use]
+ pub fn to_requirement(&self) -> String {
+ format!("{}=={}", self.name, self.version)
+ }
+}
+
+/// An installed distribution, as read by `probe.py` or ` list`.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct Dist {
+ /// Normalized distribution name.
+ pub name: PkgName,
+ /// Installed version.
+ pub version: Version,
+ /// Raw `Requires-Dist` entries. The reverse-dependency graph is built from these.
+ #[serde(default)]
+ pub requires_dist: Vec,
+ /// Raw `Requires-Python` specifier, when declared.
+ #[serde(default)]
+ pub requires_python: Option,
+}
+
+/// An installed distribution with a newer release available.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct OutdatedDist {
+ /// Normalized distribution name.
+ pub name: PkgName,
+ /// Currently installed version.
+ pub current: Version,
+ /// Newest version the index offers.
+ pub latest: Version,
+}
+
+/// Which of the two execution phases produced a result (ARCHITECTURE §8).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ExecMode {
+ /// Phase A: one engine invocation for the whole pinned set.
+ Batch,
+ /// Phase B: per-package sequential retry after Phase A failed. Skip-and-continue.
+ Isolated,
+}
+
+/// Outcome of a single package's step.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum StepStatus {
+ /// Applied successfully.
+ Ok,
+ /// Failed; carries a catalog code. Does **not** abort the batch.
+ Failed,
+ /// Not attempted — user cancelled, or dropped by a Skip decision.
+ Skipped,
+}
+
+/// One row of the summary report (DATA-FLOW §6).
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct StepResult {
+ /// Normalized distribution name.
+ pub pkg: PkgName,
+ /// Version before the step, absent for a fresh install.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub from: Option,
+ /// Version the step targeted.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub to: Option,
+ /// Whether it applied.
+ pub status: StepStatus,
+ /// Catalog code, present exactly when `status` is `Failed`.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub code: Option,
+ /// Tail of the engine's stderr for the failure detail pane.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub stderr_tail: Option,
+}
+
+/// One unsatisfied requirement reported by `pip check` / `uv pip check`.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct CheckFinding {
+ /// The distribution whose requirement is unsatisfied.
+ pub pkg: PkgName,
+ /// Human-readable requirement text as the engine printed it.
+ pub requirement: String,
+}
+
+/// Post-execution environment verification.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct CheckReport {
+ /// True when the engine reported no broken requirements.
+ pub ok: bool,
+ /// Details when `ok` is false.
+ #[serde(default)]
+ pub findings: Vec,
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn normalizes_per_pep_503() {
+ let cases = [
+ ("Requests", "requests"),
+ ("zope.interface", "zope-interface"),
+ ("typing_extensions", "typing-extensions"),
+ ("ruamel.yaml.clib", "ruamel-yaml-clib"),
+ // Runs of mixed separators collapse to a single dash.
+ ("foo._-.bar", "foo-bar"),
+ ("A", "a"),
+ ];
+ for (raw, want) in cases {
+ let got = PkgName::parse(raw).unwrap_or_else(|e| panic!("{raw:?} rejected: {e}"));
+ assert_eq!(got.as_str(), want, "normalizing {raw:?}");
+ }
+ }
+
+ #[test]
+ fn rejects_names_outside_the_pep_508_grammar() {
+ // Every one of these would be a way to smuggle something past argv validation.
+ let bad = [
+ "",
+ "-leading",
+ "trailing-",
+ ".dotstart",
+ "has space",
+ "semi;colon",
+ "amp&and",
+ "pipe|d",
+ "quote\"d",
+ "new\nline",
+ "back\\slash",
+ "sla/sh",
+ "--upgrade",
+ "requests>=2",
+ "naïve",
+ ];
+ for raw in bad {
+ assert!(PkgName::parse(raw).is_err(), "{raw:?} should be rejected");
+ }
+ }
+
+ #[test]
+ fn rejected_names_use_the_documented_code() {
+ let err = PkgName::parse("--upgrade").expect_err("flag-like name must be rejected");
+ assert_eq!(err.code, Code::PkgNotFound);
+ assert_eq!(err.code.as_str(), "PD-PKG-002");
+ }
+
+ #[test]
+ fn pinned_spec_renders_the_argv_token() {
+ let spec = PinnedSpec {
+ name: PkgName::parse("Typing_Extensions").unwrap_or_else(|_| unreachable!()),
+ version: Version("4.12.2".into()),
+ };
+ assert_eq!(spec.to_requirement(), "typing-extensions==4.12.2");
+ }
+}
diff --git a/crates/pipdock-core/src/pins/mod.rs b/crates/pipdock-core/src/pins/mod.rs
new file mode 100644
index 0000000..7e4df71
--- /dev/null
+++ b/crates/pipdock-core/src/pins/mod.rs
@@ -0,0 +1,26 @@
+//! Per-environment pins. See PRD P0-7.
+//!
+//! DATA-FLOW §9.5: pinned packages never appear in a `PlanRequest.upgrades` unless the user
+//! explicitly unpinned them in the same session. *Select all* excludes them and says how many
+//! were excluded (UI-SPEC §4).
+
+use crate::errors::Result;
+use crate::model::PkgName;
+
+/// A pin with the reason the user gave for it.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct Pin {
+ /// The pinned package.
+ pub pkg: PkgName,
+ /// Free-text justification shown in the Pins screen.
+ #[serde(default)]
+ pub reason: Option,
+}
+
+/// Pins for one environment, keyed by its `env_hash`.
+///
+/// # Errors
+/// Returns a `PD-INT-*` code when the pin store cannot be read.
+pub fn list(_env_hash: &str) -> Result> {
+ todo!("M1: read the pins table from index.db")
+}
diff --git a/crates/pipdock-core/src/plan/mod.rs b/crates/pipdock-core/src/plan/mod.rs
new file mode 100644
index 0000000..335b460
--- /dev/null
+++ b/crates/pipdock-core/src/plan/mod.rs
@@ -0,0 +1,279 @@
+//! Planning: `PlanRequest` → `ResolutionReport` → `ExecutionSummary`.
+//!
+//! See `docs/DATA-FLOW.md` §3 for the state machine and §9 for the invariants this module owns.
+
+use crate::model::{CheckReport, ExecMode, PinnedSpec, PkgName, Spec, StepResult, Version};
+
+/// How aggressively to resolve conflicts.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Strategy {
+ /// Accept whatever the resolver can satisfy. The safe default; `[C]ompatible` in the CLI.
+ Compatible,
+ /// Force the latest version of the listed packages even though it violates another
+ /// package's requirement. The UI must name what breaks before this is selectable
+ /// (UI-SPEC §4, DISCLAIMER §2).
+ ForceLatest {
+ /// Only these packages are forced; everything else stays `Compatible`.
+ overrides: Vec,
+ },
+}
+
+/// The user's intent, before the engine has said anything about it.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct PlanRequest {
+ /// Already-installed packages the user selected for upgrade.
+ #[serde(default)]
+ pub upgrades: Vec,
+ /// New packages queued in the dock bay.
+ #[serde(default)]
+ pub installs: Vec,
+ /// Conflict-handling strategy.
+ pub strategy: Strategy,
+}
+
+/// Which section of the preview a change belongs to (UI-SPEC §4).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum ChangeKind {
+ /// An installed package moving to a newer version.
+ Upgrade,
+ /// A package pulled in to satisfy something else.
+ NewDependency,
+ /// A package the user explicitly asked to install.
+ NewInstall,
+ /// A package moving to an older version to satisfy a constraint.
+ Downgrade,
+}
+
+/// One line of the preview diff.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct Change {
+ /// Normalized distribution name.
+ pub name: PkgName,
+ /// Version before, absent for a fresh install.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub from: Option,
+ /// Version the resolver chose.
+ pub to: Version,
+ /// Which preview section this belongs in.
+ pub kind: ChangeKind,
+}
+
+/// The package responsible for holding another one back.
+///
+/// ARCHITECTURE §3: the engine's report says *what* was held back; *who* is responsible comes from
+/// cross-referencing the reverse-dependency graph with each blocker's `Requires-Dist` constraint.
+/// **If attribution is ambiguous, show the constraint without a culprit rather than guessing.**
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct Blocker {
+ /// The package imposing the constraint, absent when attribution is ambiguous.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub by: Option,
+ /// The constraint text, e.g. `"requests<2.31"`.
+ pub constraint: String,
+}
+
+/// A package the resolver could not take all the way to `latest`.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct HeldBack {
+ /// Normalized distribution name.
+ pub pkg: PkgName,
+ /// The version the resolver settled on.
+ pub resolved: Version,
+ /// The version the index offers.
+ pub latest: Version,
+ /// Why it could not go further. Empty means the engine gave no attributable reason.
+ #[serde(default)]
+ pub blockers: Vec,
+}
+
+/// A `ResolutionImpossible` outcome and whatever detail the engine gave (`PD-RES-001`).
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct ImpossibleDetail {
+ /// Packages involved in the unsatisfiable set.
+ #[serde(default)]
+ pub packages: Vec,
+ /// The engine's own explanation, verbatim.
+ pub explanation: String,
+}
+
+/// The normalized dry-run result.
+///
+/// **Both adapters must emit this same shape** — that is the whole point of the `Engine` trait
+/// (ARCHITECTURE §3). The pip adapter fills it from `--dry-run --report` JSON; the uv adapter from
+/// uv's text plan output.
+///
+/// The exact field set is **provisional until spike SP-1** confirms uv's output is rich enough to
+/// populate `held_back.blockers`. If it is not, SP-1's go/no-go says v1.0 ships pip-primary with uv
+/// behind a beta flag.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct ResolutionReport {
+ /// Everything that would change if the user confirms.
+ #[serde(default)]
+ pub changes: Vec,
+ /// Packages that could not reach `latest`, with attribution.
+ #[serde(default)]
+ pub held_back: Vec,
+ /// Present when the whole resolution failed.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub impossible: Option,
+ /// The engine's untouched output, kept for the log and for bug reports.
+ pub raw: String,
+}
+
+impl ResolutionReport {
+ /// True when the preview has nothing for the user to decide, so the UI can go straight to the
+ /// confirm step (part of the 4-click budget in UI-SPEC §5).
+ #[must_use]
+ pub fn is_clean(&self) -> bool {
+ self.held_back.is_empty() && self.impossible.is_none()
+ }
+
+ /// The pinned set a confirmed plan would execute.
+ #[must_use]
+ pub fn pinned_set(&self) -> Vec {
+ self.changes
+ .iter()
+ .map(|c| PinnedSpec {
+ name: c.name.clone(),
+ version: c.to.clone(),
+ })
+ .collect()
+ }
+}
+
+/// Aggregate counts rendered as "13 successful, 2 failed, 1 skipped" (DATA-FLOW §6).
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct Counts {
+ /// Steps that applied.
+ pub ok: usize,
+ /// Steps that failed, each with a catalog code.
+ pub failed: usize,
+ /// Steps not attempted.
+ pub skipped: usize,
+}
+
+/// The end-of-run report shown in the summary sheet and emitted by `--json`.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct ExecutionSummary {
+ /// Correlates the summary with its snapshot and log ring buffer.
+ pub plan_id: String,
+ /// Which phase produced these results.
+ pub phase: ExecMode,
+ /// One row per package.
+ #[serde(default)]
+ pub results: Vec,
+ /// Post-run `engine.check()`.
+ pub check: CheckReport,
+ /// Derived from `results`; see [`ExecutionSummary::tally`].
+ pub counts: Counts,
+}
+
+impl ExecutionSummary {
+ /// Recompute `counts` from `results`.
+ ///
+ /// The counts drive the user-visible headline, so they are derived rather than accumulated by
+ /// hand — a mismatch between the rows and the headline is exactly the kind of bug
+ /// `docs/TESTING.md` §1.4 says must never regress.
+ #[must_use]
+ pub fn tally(results: &[StepResult]) -> Counts {
+ use crate::model::StepStatus;
+ let mut counts = Counts::default();
+ for r in results {
+ match r.status {
+ StepStatus::Ok => counts.ok += 1,
+ StepStatus::Failed => counts.failed += 1,
+ StepStatus::Skipped => counts.skipped += 1,
+ }
+ }
+ counts
+ }
+}
+
+/// DATA-FLOW §9.3: a report older than this is refused by `plan_execute` and must be re-resolved.
+pub const PLAN_MAX_AGE: std::time::Duration = std::time::Duration::from_secs(10 * 60);
+
+/// DATA-FLOW §3: after this many conflict-decision rounds the UI requires manual pruning, which
+/// prevents decision ping-pong.
+pub const MAX_CONFLICT_ROUNDS: u8 = 3;
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::model::StepStatus;
+
+ fn step(pkg: &str, status: StepStatus) -> StepResult {
+ StepResult {
+ pkg: PkgName::parse(pkg).unwrap(),
+ from: None,
+ to: None,
+ status,
+ code: None,
+ stderr_tail: None,
+ }
+ }
+
+ #[test]
+ fn tally_matches_the_documented_headline() {
+ // The example from DATA-FLOW §6: "13 successful, 2 failed, 1 skipped".
+ let mut results: Vec = (0..13)
+ .map(|i| step(&format!("ok{i}"), StepStatus::Ok))
+ .collect();
+ results.extend((0..2).map(|i| step(&format!("bad{i}"), StepStatus::Failed)));
+ results.push(step("skipped0", StepStatus::Skipped));
+
+ assert_eq!(
+ ExecutionSummary::tally(&results),
+ Counts {
+ ok: 13,
+ failed: 2,
+ skipped: 1
+ }
+ );
+ }
+
+ #[test]
+ fn empty_run_tallies_to_zero() {
+ assert_eq!(ExecutionSummary::tally(&[]), Counts::default());
+ }
+
+ #[test]
+ fn a_report_with_held_back_items_is_not_clean() {
+ let held = HeldBack {
+ pkg: PkgName::parse("requests").unwrap(),
+ resolved: Version("2.30.0".into()),
+ latest: Version("2.32.3".into()),
+ blockers: vec![Blocker {
+ by: Some(PkgName::parse("apiclient").unwrap()),
+ constraint: "requests<2.31".into(),
+ }],
+ };
+ let report = ResolutionReport {
+ changes: vec![],
+ held_back: vec![held],
+ impossible: None,
+ raw: String::new(),
+ };
+ assert!(!report.is_clean());
+ }
+
+ #[test]
+ fn pinned_set_mirrors_the_changes() {
+ let report = ResolutionReport {
+ changes: vec![Change {
+ name: PkgName::parse("httpx").unwrap(),
+ from: Some(Version("0.27.0".into())),
+ to: Version("0.28.1".into()),
+ kind: ChangeKind::Upgrade,
+ }],
+ held_back: vec![],
+ impossible: None,
+ raw: String::new(),
+ };
+ assert!(report.is_clean());
+ let pinned = report.pinned_set();
+ assert_eq!(pinned.len(), 1);
+ assert_eq!(pinned[0].to_requirement(), "httpx==0.28.1");
+ }
+}
diff --git a/crates/pipdock-core/src/probe.py b/crates/pipdock-core/src/probe.py
new file mode 100644
index 0000000..eb67922
--- /dev/null
+++ b/crates/pipdock-core/src/probe.py
@@ -0,0 +1,142 @@
+"""PipDock environment probe.
+
+Prints a single JSON document describing the interpreter it runs under and every
+distribution installed in it. Rust cannot cheaply read a foreign environment's
+metadata, so this helper is executed as:
+
+ -I --json
+
+Constraints (docs/ARCHITECTURE.md section 4, docs/SECURITY.md section 2):
+
+* Standard library only. No third-party imports, ever -- the environments this
+ runs in are the user's, and may contain anything.
+* Python 3.10 floor: `importlib.metadata` only, no `packaging`.
+* Run with -I so PYTHONPATH and user site are ignored and a poisoned environment
+ cannot inject code into the probe.
+* Written to a temp file with a random name per invocation; never installed.
+
+Output shape:
+
+ {"python": "3.12.4", "prefix": "...", "externally_managed": false,
+ "dists": [{"name": "requests", "version": "2.32.3",
+ "requires_dist": ["urllib3<3,>=1.21.1"],
+ "requires_python": ">=3.8"}]}
+
+Any failure prints {"error": ...} on stdout and exits non-zero, which the core
+classifies as PD-ENV-003.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import sysconfig
+
+SCHEMA_VERSION = 1
+
+
+def _normalize(name: str) -> str:
+ """PEP 503 normalization, mirrored in model.rs so both sides agree on identity."""
+ out: list[str] = []
+ prev_sep = False
+ for ch in name:
+ if ch in "-_.":
+ if not prev_sep:
+ out.append("-")
+ prev_sep = True
+ else:
+ out.append(ch.lower())
+ prev_sep = False
+ return "".join(out)
+
+
+def _externally_managed() -> bool:
+ """Detect the PEP 668 marker.
+
+ The marker sits next to the stdlib in the `stdlib` scheme path. Its mere
+ presence is what pip keys off, so PipDock does the same -- contents are not
+ parsed. Drives PD-ENV-002.
+ """
+ candidates = []
+ for key in ("stdlib", "platstdlib"):
+ try:
+ path = sysconfig.get_path(key)
+ except (KeyError, OSError):
+ continue
+ if path:
+ candidates.append(os.path.join(path, "EXTERNALLY-MANAGED"))
+ return any(os.path.isfile(p) for p in candidates)
+
+
+def _dists() -> list[dict[str, object]]:
+ """Read installed distribution metadata.
+
+ A single unreadable distribution must not fail the whole probe -- broken
+ metadata in one package is common and the user still needs the rest of the
+ list. Such entries are reported with an `error` field instead.
+ """
+ from importlib.metadata import distributions
+
+ out: list[dict[str, object]] = []
+ for dist in distributions():
+ try:
+ meta = dist.metadata
+ if meta is None:
+ continue
+ # Use .get(), not subscripting: on Python 3.14 a missing header returns None with a
+ # DeprecationWarning ("Implicit None on return values is deprecated") and is slated to
+ # raise KeyError. The warning goes to stderr and would otherwise pollute every probe
+ # run against a 3.14 environment.
+ raw_name = meta.get("Name")
+ if not raw_name:
+ continue
+ out.append(
+ {
+ "name": _normalize(raw_name),
+ "version": dist.version or "",
+ "requires_dist": list(dist.requires or []),
+ "requires_python": meta.get("Requires-Python"),
+ }
+ )
+ except Exception as exc: # noqa: BLE001 - one bad dist must not sink the probe
+ out.append({"name": None, "error": f"{type(exc).__name__}: {exc}"})
+
+ out.sort(key=lambda d: (d.get("name") or ""))
+ return out
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description="PipDock environment probe")
+ parser.add_argument(
+ "--json",
+ action="store_true",
+ help="emit JSON (the only supported mode; accepted for explicitness)",
+ )
+ parser.parse_args(argv)
+
+ try:
+ payload = {
+ "schema": SCHEMA_VERSION,
+ "python": ".".join(str(p) for p in sys.version_info[:3]),
+ "implementation": sys.implementation.name,
+ "prefix": sys.prefix,
+ "base_prefix": sys.base_prefix,
+ "executable": sys.executable,
+ "is_venv": sys.prefix != sys.base_prefix,
+ "externally_managed": _externally_managed(),
+ "dists": _dists(),
+ }
+ except Exception as exc: # noqa: BLE001 - the core turns this into PD-ENV-003
+ json.dump({"error": f"{type(exc).__name__}: {exc}"}, sys.stdout)
+ sys.stdout.write("\n")
+ return 1
+
+ json.dump(payload, sys.stdout, ensure_ascii=False)
+ sys.stdout.write("\n")
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/crates/pipdock-core/src/snapshot/mod.rs b/crates/pipdock-core/src/snapshot/mod.rs
new file mode 100644
index 0000000..b00d6e9
--- /dev/null
+++ b/crates/pipdock-core/src/snapshot/mod.rs
@@ -0,0 +1,23 @@
+//! Freeze snapshots, diffs and minimal-ops rollback. See DATA-FLOW §8.
+//!
+//! DATA-FLOW §9.2 is absolute: no mutating engine call happens without a successful snapshot
+//! write. A failed write aborts the plan and executes nothing (`PD-SNP-001`).
+
+use crate::errors::Result;
+
+/// A captured environment state: a freeze file plus its metadata sidecar.
+#[derive(Debug)]
+pub struct Snapshot;
+
+/// Write a snapshot for `env_hash` before a batch runs.
+///
+/// # Errors
+/// Returns `PD-SNP-001` on any write failure. **Callers must abort the plan on error** — this is
+/// the one failure mode that is not skip-and-continue.
+pub fn create(_env_hash: &str) -> Result {
+ todo!("M1: engine freeze + .meta.json (trigger, engine, package count, app version)")
+}
+
+/// Snapshot retention: `%LOCALAPPDATA%\PipDock\snapshots\\.freeze.txt`
+/// alongside `.meta.json` (ARCHITECTURE §6).
+pub const SNAPSHOT_DIR: &str = "snapshots";
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 3b1ae11..82d9c60 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -129,5 +129,6 @@ Zustand stores: `useEnvStore`, `usePlanStore`, `useIndexStore`, `useSettingsStor
| uv engine | latest stable (0.9.x line at writing); minimum pinned after SP-1 |
| Managed Pythons | 3.10 – 3.14 (3.9 is EOL) |
| Windows | 10 (1809+) / 11; WebView2 Evergreen assumed present; `longPathAware` manifest enabled |
+| rusqlite | **held at 0.37** (`libsqlite3-sys` 0.35). 0.40 pulls `libsqlite3-sys` 0.38.1, whose build script uses the unstable `cfg_select!` and therefore does not compile on stable Rust 1.94.1. Revisit when the toolchain advances. |
Dependabot + `cargo audit` + `npm audit` in CI keep this table honest (RELEASE-CI.md §2).
diff --git a/rust-toolchain.toml b/rust-toolchain.toml
new file mode 100644
index 0000000..866b988
--- /dev/null
+++ b/rust-toolchain.toml
@@ -0,0 +1,5 @@
+[toolchain]
+channel = "1.94.1"
+components = ["rustfmt", "clippy"]
+targets = ["x86_64-pc-windows-msvc"]
+profile = "minimal"
diff --git a/spikes/README.md b/spikes/README.md
new file mode 100644
index 0000000..acfdcd6
--- /dev/null
+++ b/spikes/README.md
@@ -0,0 +1,58 @@
+# Phase 0 spikes
+
+`docs/ROADMAP.md` Phase 0: **before any feature code**, because the architecture rests on
+assumptions that have to be checked on a real machine. Each spike is a small script here plus
+fixtures committed to `crates/pipdock-core/tests/fixtures/`, and its answer is recorded below.
+
+| Spike | Question | Status |
+|---|---|---|
+| SP-1 | Exact shape of `uv pip install -U --dry-run`; is held-back attribution derivable? | not started — **blocked on installing uv** |
+| SP-2 | `pip --dry-run --report` JSON + real stderr for every catalog code | not started |
+| SP-3 | PEP 691 index size, SQLite ingest time, fuzzy-search latency over ~600 k names | not started |
+| SP-4 | pip-audit invocation for a foreign environment | not started |
+| SP-5 | Held-back attribution accuracy on a real numpy/scipy/pandas tangle | not started |
+| SP-6 | Windows env discovery sweep (PEP 514, `py -0p`, Store Python, uv-managed) | one finding recorded below |
+
+SP-1 is a **go/no-go**: if uv's plan output is too lossy to populate
+`ResolutionReport::held_back[].blockers`, v1.0 ships pip-primary with uv behind a beta-engine flag.
+
+## Findings
+
+### SP-6 — `probe.py -I` hides user-site packages (measured 2026-07-27)
+
+`docs/SECURITY.md` §2 specifies running the probe with `-I` (isolated mode) so a poisoned
+environment cannot inject code into it. Isolated mode also disables **user site-packages**, and on
+a system Python that is where most packages actually live.
+
+Measured against `C:\Python314` on the dev machine:
+
+| View | Distributions |
+|---|---|
+| `probe.py` with `-I` | 352 |
+| `probe.py` without `-I` | 376 |
+| `pip list` | 375 |
+
+So `-I` hides **24 packages** that pip itself reports, and PipDock's Installed tab would disagree
+with `pip list` by that much. The remaining 376 vs 375 gap is a second, smaller question — likely a
+shadowed distribution that `importlib.metadata` reports twice and pip de-duplicates by normalized
+name.
+
+This does not affect the primary target: a venv has no user site, so all three numbers agree. It
+affects **non-venv system Pythons that are not PEP 668-marked** — `C:\Python314` reports
+`externally_managed: false`, so nothing blocks PipDock from managing it.
+
+**Open decision for SP-6** (do not resolve unilaterally — it trades a documented security control
+against list accuracy):
+
+- keep `-I` and show a "user-site packages not shown" note on non-venv environments; or
+- drop to `-E` (ignore `PYTHONPATH` only, keep user site), accepting that a package in user site
+ can influence the probe's imports; or
+- run the probe twice and reconcile, at the cost of a second interpreter start per scan.
+
+### SP-6 — Python 3.14 metadata deprecation (fixed 2026-07-27)
+
+Subscripting `dist.metadata["Requires-Python"]` for an absent header emits
+`DeprecationWarning: Implicit None on return values is deprecated and will raise KeyErrors` on
+Python 3.14, on **stderr**, for many distributions. `probe.py` now uses `.get()`. Worth keeping in
+mind generally: the probe must stay clean on stderr, because the core treats probe noise as
+`PD-ENV-003`.