feat(core): the tools manifest, and a predicate that says why a re-sync is owed

CODE-HEALTH-SPEC §2 gives the tools directory a manifest.json holding "installed pin set
+ hash; mismatch with shipped pins => re-sync". This is that, plus the check that decides.

`needs_sync` compares the hash *and* looks for the files. A hash comparison alone reports
Fresh for a venv whose ruff.exe an antivirus quarantined — which is exactly the case
PD-HLT-001's shipped copy is about ("Re-sync the tools environment"), so the one state the
code already promises to detect would have been the one it could not see.
`a_quarantined_tool_is_detected_even_though_the_hash_still_matches` holds that.

SyncNeed is an enum, not a bool, for the same reason: doctor and P4's screen have to say
why, and PinsChanged carries both hashes so a Dependabot bump is legible rather than just
"something moved".

ToolsManifest is on-disk only and deliberately not in SCHEMA_TYPES — P2 has no IPC
surface, and a type that crosses the bridge is a contract that has to be kept. Its fields
already serialize camelCase so the rename that would need snapshot::Meta's #[serde(alias)]
treatment never has to happen; a test pins that spelling now.

Absent, unreadable and corrupt manifests all read as NeverSynced. They mean the same thing
to every caller, and distinguishing them would offer the user a choice they cannot act on.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-12 21:31:22 +07:00
1 parent 3ff1d58830
commit ea01713377
1 file changed
+276
+276
View File
@@ -5,6 +5,7 @@
//! confirm. PipDock never edits `pyproject.toml` or `requirements.txt` for the user.
use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
use crate::errors::{Code, PdError, Result};
use crate::model::{PinnedSpec, PkgName, Version};
@@ -128,6 +129,140 @@ pub fn requirements_body(pins: &[PinnedSpec]) -> String {
})
}
/// The manifest filename inside the tools directory.
const MANIFEST_FILE: &str = "manifest.json";
/// `<app_data>\tools` — the layout CODE-HEALTH-SPEC §2 draws.
#[must_use]
pub fn tools_dir(app_data: &Path) -> PathBuf {
app_data.join("tools")
}
/// `<tools_dir>\.venv\Scripts\python.exe`.
#[must_use]
pub fn venv_python(tools_dir: &Path) -> PathBuf {
tools_dir.join(".venv").join("Scripts").join("python.exe")
}
/// `<tools_dir>\.venv\Scripts\<tool>.exe` — the console script pip installs for each tool.
#[must_use]
pub fn tool_exe(tools_dir: &Path, tool: &str) -> PathBuf {
tools_dir
.join(".venv")
.join("Scripts")
.join(format!("{tool}.exe"))
}
/// What was installed into the tools venv, and against which pins.
///
/// **On-disk only, for now.** It deliberately does not derive `JsonSchema` and is not in
/// `SCHEMA_TYPES`: P2 has no IPC surface, and a type that crosses the bridge is a contract that has
/// to be kept. The day P3 or P4 returns it from a Tauri command it inherits `snapshot::Meta`'s
/// discipline — `#[serde(alias)]` on every renamed field, because manifests written by earlier
/// builds will be on disk and a manifest that no longer parses silently re-syncs the venv on every
/// launch. The field names below already serialize camelCase, so that rename should never happen.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ToolsManifest {
/// SHA-256 of the normalized pin set — see [`pins_hash`].
pub pins_hash: String,
/// The pins as installed, `name==version`, sorted by name.
pub pins: Vec<String>,
/// The version each tool actually reported from `--version`, keyed by tool name.
///
/// Reported, not assumed: a pin says what was requested, this says what answered. P3's
/// `HealthReport.toolVersions` (CODE-HEALTH-SPEC §5) is this map.
pub tools: BTreeMap<String, String>,
/// `exec::canonical_interpreter` of the venv's python.
///
/// **An identity, not a path to execute.** It is case-folded (SP-6), which is fine to run on
/// Windows and therefore tempting; the path actually invoked is always re-derived from the
/// tools directory through [`venv_python`], so that a moved app-data folder still works.
pub python: String,
/// The interpreter's version, e.g. `"3.14.6"`.
pub python_version: String,
/// The build that wrote it, as `snapshot::Meta` records.
pub app_version: String,
/// When it was written, RFC 3339.
pub synced_at: String,
}
/// Why a re-sync is owed, or that it is not.
///
/// An enum rather than a `bool` because `doctor` and P4's Health screen have to *say* why, and
/// because `ToolMissing` is the state `PD-HLT-001`'s shipped copy is about ("Re-sync the tools
/// environment"). A `bool` would make "antivirus quarantined `ruff.exe`" indistinguishable from
/// "up to date".
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
#[serde(tag = "state", rename_all = "camelCase")]
pub enum SyncNeed {
/// The venv matches the shipped pins and every tool is on disk.
Fresh,
/// No manifest — never synced, or a previous sync was interrupted before it finished.
NeverSynced,
/// The shipped pin set has moved since the venv was built, typically a Dependabot bump.
#[serde(rename_all = "camelCase")]
PinsChanged {
/// The hash the manifest recorded.
from: String,
/// The hash this build ships.
to: String,
},
/// The manifest is current but the venv's interpreter is gone.
InterpreterGone,
/// The manifest is current but a tool's console script is not on disk.
ToolMissing(String),
}
impl SyncNeed {
/// Whether a sync has to run.
#[must_use]
pub fn is_needed(&self) -> bool {
!matches!(self, Self::Fresh)
}
}
/// Read `manifest.json`, if there is a readable one.
///
/// `None` for absent, unreadable and unparseable alike — all three mean the same thing to every
/// caller, which is "re-sync". Distinguishing them would offer the user a choice they cannot act on.
#[must_use]
pub fn read_manifest(tools_dir: &Path) -> Option<ToolsManifest> {
let raw = std::fs::read_to_string(tools_dir.join(MANIFEST_FILE)).ok()?;
serde_json::from_str(&raw).ok()
}
/// Whether the tools venv matches the shipped pins **and** its tools are actually on disk.
///
/// Both halves matter. Comparing hashes alone would report `Fresh` for a venv whose `ruff.exe` an
/// antivirus quarantined, which is precisely the case `PD-HLT-001` exists for.
///
/// # Errors
/// `PD-PKG-002` when the shipped ledger is malformed — a build-time mistake, surfaced here because
/// this is the first thing every caller does.
pub fn needs_sync(tools_dir: &Path) -> Result<SyncNeed> {
let want = pins_hash(&pins()?);
let Some(manifest) = read_manifest(tools_dir) else {
return Ok(SyncNeed::NeverSynced);
};
if manifest.pins_hash != want {
return Ok(SyncNeed::PinsChanged {
from: manifest.pins_hash,
to: want,
});
}
if !venv_python(tools_dir).is_file() {
return Ok(SyncNeed::InterpreterGone);
}
for tool in HEALTH_TOOLS {
if !tool_exe(tools_dir, tool).is_file() {
return Ok(SyncNeed::ToolMissing((*tool).to_owned()));
}
}
Ok(SyncNeed::Fresh)
}
/// Sort by normalized name, so a reordered ledger is not a re-sync.
fn sorted_by_name(mut pins: Vec<PinnedSpec>) -> Vec<PinnedSpec> {
pins.sort_by(|a, b| a.name.cmp(&b.name));
@@ -291,6 +426,147 @@ mod tests {
assert!(body.ends_with('\n'));
}
// -- the manifest and the re-sync predicate ---------------------------------
#[test]
fn a_directory_with_no_manifest_has_never_been_synced() {
let dir = scratch("never");
assert_eq!(
needs_sync(&dir).expect("ledger parses"),
SyncNeed::NeverSynced
);
assert!(needs_sync(&dir).expect("ledger parses").is_needed());
}
#[test]
fn an_unparseable_manifest_reads_as_never_synced() {
// Not its own state: absent, unreadable and corrupt all mean "re-sync" to every caller.
let dir = scratch("corrupt");
write_venv(&dir, HEALTH_TOOLS);
std::fs::write(dir.join(MANIFEST_FILE), "{ not json").expect("write");
assert_eq!(
needs_sync(&dir).expect("ledger parses"),
SyncNeed::NeverSynced
);
}
#[test]
fn a_matching_manifest_with_every_tool_present_is_fresh() {
let dir = scratch("fresh");
write_venv(&dir, HEALTH_TOOLS);
write_manifest(&dir, &pins_hash(&pins().expect("ledger parses")));
assert_eq!(needs_sync(&dir).expect("ledger parses"), SyncNeed::Fresh);
assert!(!needs_sync(&dir).expect("ledger parses").is_needed());
}
/// The case a hash comparison alone would call `Fresh`, and the one PD-HLT-001 is about.
#[test]
fn a_quarantined_tool_is_detected_even_though_the_hash_still_matches() {
let dir = scratch("quarantined");
write_venv(&dir, &["deptry", "vulture"]); // ruff.exe never written
write_manifest(&dir, &pins_hash(&pins().expect("ledger parses")));
assert_eq!(
needs_sync(&dir).expect("ledger parses"),
SyncNeed::ToolMissing("ruff".to_owned())
);
}
#[test]
fn a_stale_hash_reports_both_sides_so_the_user_can_see_what_moved() {
let dir = scratch("stale");
write_venv(&dir, HEALTH_TOOLS);
write_manifest(&dir, &"0".repeat(64));
let want = pins_hash(&pins().expect("ledger parses"));
assert_eq!(
needs_sync(&dir).expect("ledger parses"),
SyncNeed::PinsChanged {
from: "0".repeat(64),
to: want,
}
);
}
#[test]
fn a_missing_interpreter_is_its_own_state() {
let dir = scratch("gone");
write_venv(&dir, HEALTH_TOOLS);
std::fs::remove_file(venv_python(&dir)).expect("remove python");
write_manifest(&dir, &pins_hash(&pins().expect("ledger parses")));
assert_eq!(
needs_sync(&dir).expect("ledger parses"),
SyncNeed::InterpreterGone
);
}
#[test]
fn a_manifest_round_trips_through_its_on_disk_form() {
let dir = scratch("roundtrip");
write_venv(&dir, HEALTH_TOOLS);
write_manifest(&dir, "abc");
let read = read_manifest(&dir).expect("written manifest is readable");
assert_eq!(read.pins_hash, "abc");
assert_eq!(read.tools.get("ruff").map(String::as_str), Some("0.16.0"));
}
/// The camelCase spelling is the shape a future IPC surface would inherit, so pin it now —
/// a later rename is what would need `#[serde(alias)]`.
#[test]
fn the_manifest_serializes_camel_case() {
let dir = scratch("camel");
write_venv(&dir, HEALTH_TOOLS);
write_manifest(&dir, "abc");
let raw = std::fs::read_to_string(dir.join(MANIFEST_FILE)).expect("read");
for key in ["pinsHash", "pythonVersion", "appVersion", "syncedAt"] {
assert!(raw.contains(key), "expected {key} in {raw}");
}
assert!(!raw.contains('_'), "no snake_case key may survive: {raw}");
}
/// A scratch directory of our own, cleaned on entry. Matches `store`'s idiom rather than
/// adding a `tempfile` dev-dependency that would have to clear `cargo audit` forever.
fn scratch(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("pd-health-{name}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).expect("create scratch dir");
dir
}
/// Lay out a plausible venv: an interpreter plus a console script per named tool.
fn write_venv(tools_dir: &Path, tools: &[&str]) {
let scripts = tools_dir.join(".venv").join("Scripts");
std::fs::create_dir_all(&scripts).expect("create Scripts");
std::fs::write(venv_python(tools_dir), "").expect("write python.exe");
for tool in tools {
std::fs::write(tool_exe(tools_dir, tool), "").expect("write tool");
}
}
fn write_manifest(tools_dir: &Path, hash: &str) {
let installed = pins().expect("ledger parses");
let manifest = ToolsManifest {
pins_hash: hash.to_owned(),
pins: installed.iter().map(PinnedSpec::to_requirement).collect(),
tools: installed
.iter()
.map(|p| (p.name.to_string(), p.version.to_string()))
.collect(),
python: "c:\\x\\.venv\\scripts\\python.exe".to_owned(),
python_version: "3.14.6".to_owned(),
app_version: env!("CARGO_PKG_VERSION").to_owned(),
synced_at: "2026-08-12T00:00:00Z".to_owned(),
};
let json = serde_json::to_string_pretty(&manifest).expect("serialize");
std::fs::write(tools_dir.join(MANIFEST_FILE), json).expect("write manifest");
}
/// Parse a ledger fragment and hash it, the way `pins`/`pins_hash` do for the real one.
fn hash_of(ledger: &str) -> String {
let parsed = parse_ledger(ledger).expect("fragment parses");