test(cli): add the L4 golden-output suite

TESTING L4 has been owed since M1. `assert_cmd` and `insta` were already
dev-dependencies with zero references and no `tests/` directory in the crate.

TESTING section 2 asks for "golden-output tests per command against a mocked core",
and the CLI has no seam to mock at: run.rs builds its engine from the global
options and drives a real interpreter, and print_preview / print_summary are
private functions that println! rather than return. So the preview and summary
renderings stay with L2 against real environments, and what is goldened here is
everything deterministic without one -- the clap surface, the exit-code table
CLI-SPEC section 5 calls a public contract, the --json error envelope, and
`schema <T>` for all fifteen SCHEMA_TYPES.

That last group is the point. It pins two contract bugs the M2 bridge has to fix,
so the fix arrives as a reviewable diff rather than as an invisible change:

  - ExecutionSummary serializes plan_id and stderr_tail, where DATA-FLOW section 6
    documents planId and stderrTail
  - Code serializes as its Rust variant name ("EnvInterpreterMissing"), where
    ERROR-CATALOG documents the wire code (PD-ENV-001)

Both are visible in the committed snapshots today. The error envelope, which
main.rs hand-builds rather than deriving, already has the documented shape -- so
the same binary currently disagrees with itself across its two --json paths.

Snapshots are filtered for the executable name (pipdock.exe on Windows) and the
crate version, so they record the contract rather than the machine or the release.
insta gains its `filters` feature for that.

183 tests pass, fmt and clippy clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-07-29 20:26:01 +07:00
1 parent 465b54f7e8
commit 1c728df64c
49 files changed
+3295 -1

No files matched your search

Generated
+20
View File
@@ -1950,8 +1950,10 @@ checksum = "86f0f8fee8c926415c58d6ae43a08523a26faccb2323f5e6b644fe7dd4ef6b82"
dependencies = [
"console",
"once_cell",
"regex",
"serde",
"similar",
"strip-ansi-escapes",
"tempfile",
]
@@ -3954,6 +3956,15 @@ dependencies = [
"quote",
]
[[package]]
name = "strip-ansi-escapes"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2a8f8038e7e7969abb3f1b7c2a811225e9296da208539e0f79c5251d6cac0025"
dependencies = [
"vte",
]
[[package]]
name = "strsim"
version = "0.11.1"
@@ -5020,6 +5031,15 @@ dependencies = [
"libc",
]
[[package]]
name = "vte"
version = "0.14.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "231fdcd7ef3037e8330d8e17e61011a2c244126acc0a982f4040ac3f9f0bc077"
dependencies = [
"memchr",
]
[[package]]
name = "wait-timeout"
version = "0.2.1"
+3 -1
View File
@@ -26,4 +26,6 @@ tracing-subscriber = { version = "0.3.23", features = ["env-filter"] }
[dev-dependencies]
assert_cmd = "2.2.2"
insta = "1.48.0"
# `filters` gives `Settings::add_filter`, used to keep the crate version out of the help
# snapshots so a release bump does not churn every golden in tests/golden.rs.
insta = { version = "1.48.0", features = ["filters"] }
+252
View File
@@ -0,0 +1,252 @@
//! TESTING L4 — golden output for the CLI surface.
//!
//! Scope note. TESTING §2 asks for "golden-output tests per command against a mocked core". The
//! CLI has no seam to mock at: `run.rs` builds its engine from the global options and drives a
//! real interpreter, and `print_preview` / `print_summary` are private functions that `println!`
//! rather than return. So the preview and summary renderings are covered by L2 against real
//! environments, and what is goldened here is everything that is deterministic without one:
//!
//! * the clap surface — every command's help, which is the flag contract scripts read;
//! * the exhaustive exit-code table (CLI-SPEC §5), which the docs call a public contract;
//! * the `--json` error envelope;
//! * `pipdock schema <T>` for all 15 types in `SCHEMA_TYPES`, which is the JSON contract
//! CLI-SPEC §6 promises consumers can pin against.
//!
//! That last one earns its keep beyond regression cover: the M2 bridge changes the wire format to
//! camelCase and makes `Code` serialize as `PD-*` rather than as its Rust variant name. These
//! snapshots are how that change becomes reviewable instead of invisible.
//!
//! When the flow refactor moves rendering out of the CLI (ROADMAP Phase 2 — "the flow never
//! prints"), the preview and summary renderers become pure functions of core types and should
//! gain their own snapshots here.
// Same allowance the core integration tests take: in a test a panic *is* the failure report, and
// the workspace-wide deny exists to keep them out of shipping code.
#![allow(clippy::unwrap_used, clippy::expect_used)]
use assert_cmd::Command;
/// Types `pipdock schema` can emit. Kept in step with `pipdock_core::plan::SCHEMA_TYPES` by
/// `schema_lists_exactly_the_documented_types` below, so this list cannot silently fall behind.
const SCHEMA_TYPES: &[&str] = &[
"Dist",
"OutdatedDist",
"PyEnv",
"CheckReport",
"StepResult",
"PlanRequest",
"ResolutionReport",
"ExecutionSummary",
"Pin",
"GuardReport",
"Diff",
"SnapshotMeta",
"Hit",
"PackageMeta",
"Code",
];
fn pipdock() -> Command {
let mut cmd = Command::cargo_bin("pipdock").expect("the `pipdock` binary builds");
// Colour and width leak the terminal into the snapshot; pin both.
cmd.env("NO_COLOR", "1").env("COLUMNS", "100");
cmd
}
fn stdout_of(args: &[&str]) -> String {
let out = pipdock().args(args).output().expect("the process runs");
String::from_utf8_lossy(&out.stdout).replace("\r\n", "\n")
}
fn stderr_of(args: &[&str]) -> String {
let out = pipdock().args(args).output().expect("the process runs");
String::from_utf8_lossy(&out.stderr).replace("\r\n", "\n")
}
fn code_of(args: &[&str]) -> i32 {
pipdock()
.args(args)
.output()
.expect("the process runs")
.status
.code()
.expect("the process exits rather than being signalled")
}
/// Two things would otherwise make these snapshots record the machine rather than the contract:
/// clap prints the real executable name in every usage line, which is `pipdock.exe` on Windows
/// and `pipdock` everywhere else; and the crate version appears wherever clap renders it, so a
/// release bump would churn the whole file.
fn settings() -> insta::Settings {
let mut s = insta::Settings::clone_current();
s.add_filter(r"\bpipdock\.exe\b", "pipdock");
s.add_filter(r"\b\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?\b", "[VERSION]");
s
}
// -- the clap surface ---------------------------------------------------------------------------
#[test]
fn top_level_help_is_stable() {
settings().bind(|| insta::assert_snapshot!("help", stdout_of(&["--help"])));
}
#[test]
fn every_command_documents_itself() {
// Drives the same list CLI-SPEC §3 enumerates. A command added without a doc comment, or one
// whose flags change shape, shows up here as a diff rather than in a user's script.
for cmd in [
"env",
"list",
"search",
"info",
"install",
"update",
"uninstall",
"pin",
"snapshot",
"doctor",
"health",
"pip-upgrade",
"engine",
"index",
"schema",
"self",
] {
settings().bind(|| {
insta::assert_snapshot!(format!("help-{cmd}"), stdout_of(&[cmd, "--help"]));
});
}
}
#[test]
fn subcommand_help_is_stable() {
for (parent, child) in [
("env", "list"),
("env", "use"),
("pin", "add"),
("pin", "remove"),
("pin", "list"),
("snapshot", "list"),
("snapshot", "create"),
("snapshot", "diff"),
("snapshot", "rollback"),
("index", "refresh"),
("self", "report-bug"),
] {
settings().bind(|| {
insta::assert_snapshot!(
format!("help-{parent}-{child}"),
stdout_of(&[parent, child, "--help"])
);
});
}
}
// -- exit codes (CLI-SPEC §5) -------------------------------------------------------------------
#[test]
fn the_exit_code_table_holds() {
// "Scripts pin against these, so the numbers are a public contract" (main.rs). Every row here
// is reachable without touching a real interpreter; the rest are exercised by L2.
let cases: &[(&str, &[&str], i32)] = &[
("help exits clean", &["--help"], 0),
("version exits clean", &["--version"], 0),
("a valid schema type", &["schema", "Dist"], 0),
// clap's own usage errors are 2, distinct from PlanAborted, which is also 2 but only
// reachable once a plan exists.
("an unknown command", &["no-such-command"], 2),
("a missing required argument", &["info"], 2),
("an unparseable engine", &["--engine", "cargo", "list"], 2),
// PD-ENV-001 -> EnvError.
(
"a missing environment",
&["list", "--env", "C:/definitely/not/here"],
3,
),
(
"a missing environment, doctor",
&["doctor", "--env", "C:/definitely/not/here"],
3,
),
];
let mut failures = Vec::new();
for (what, args, want) in cases {
let got = code_of(args);
if got != *want {
failures.push(format!(
"{what}: `pipdock {}` exited {got}, want {want}",
args.join(" ")
));
}
}
assert!(failures.is_empty(), "{}", failures.join("\n"));
}
#[test]
fn conflicting_verbosity_flags_are_refused() {
// `quiet` declares conflicts_with = "verbose"; if that attribute is dropped the two silently
// both apply and the log level becomes whichever clap saw last.
assert_eq!(code_of(&["--quiet", "--verbose", "list"]), 2);
}
// -- the error envelope -------------------------------------------------------------------------
#[test]
fn the_json_error_envelope_is_stable() {
// DATA-FLOW §6 and ERROR-CATALOG §3 fix this shape: a wire code, a developer-facing message,
// and a stderr tail. `code` must be the catalog code, never the Rust variant name.
let out = stdout_of(&["list", "--env", "C:/definitely/not/here", "--json"]);
insta::assert_snapshot!("error-envelope-json", out);
}
#[test]
fn the_human_error_line_carries_its_code() {
// ERROR-CATALOG §3: every user-visible failure carries exactly one catalog code.
let err = stderr_of(&["list", "--env", "C:/definitely/not/here"]);
insta::assert_snapshot!("error-envelope-human", err);
assert!(
err.contains("PD-ENV-001"),
"the code must be in the message: {err}"
);
}
#[test]
fn an_unknown_schema_type_lists_the_known_ones() {
insta::assert_snapshot!("schema-unknown-type", stderr_of(&["schema", "NoSuchType"]));
}
// -- the JSON contract (CLI-SPEC §6) ------------------------------------------------------------
#[test]
fn schema_lists_exactly_the_documented_types() {
// Guards the local copy above against `SCHEMA_TYPES` drifting in core. The error path prints
// the real list, so it is the cheapest way to read it back out of the binary.
let listed = stderr_of(&["schema", "NoSuchType"]);
let (_, tail) = listed
.split_once("known types: ")
.unwrap_or_else(|| panic!("the unknown-type message no longer lists the types:\n{listed}"));
let from_binary: Vec<&str> = tail.trim().split(", ").map(str::trim).collect();
assert_eq!(
from_binary, SCHEMA_TYPES,
"core's SCHEMA_TYPES and this test's copy disagree"
);
}
#[test]
fn every_schema_is_valid_json_and_stable() {
// These snapshots are the review surface for the M2 wire-format change: camelCase properties
// and `Code` serializing as PD-* both land here first.
for ty in SCHEMA_TYPES {
let out = stdout_of(&["schema", ty]);
let parsed: serde_json::Value =
serde_json::from_str(&out).unwrap_or_else(|e| panic!("`schema {ty}` is not JSON: {e}"));
assert!(
parsed.get("$schema").is_some() || parsed.get("title").is_some(),
"`schema {ty}` does not look like a JSON Schema document"
);
insta::assert_snapshot!(format!("schema-{ty}"), out);
}
}
@@ -0,0 +1,5 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: err
---
error[PD-ENV-001]: no interpreter at C:/definitely/not/here
@@ -0,0 +1,5 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{"code":"PD-ENV-001","message":"no interpreter at C:/definitely/not/here","stderrTail":null}
@@ -0,0 +1,41 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Engine check and environment sanity report
Usage: pipdock doctor [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,42 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Show or set the configured engine
Usage: pipdock engine [OPTIONS] [ENGINE]
Arguments:
[ENGINE]
Engine to switch to; omit to print the current one
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,41 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[parent, child, \"--help\"])"
---
List discovered environments, their sources and PEP 668 flags
Usage: pipdock env list [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,45 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[parent, child, \"--help\"])"
---
Set the default environment
Usage: pipdock env use [OPTIONS] <PATH>
Arguments:
<PATH>
Interpreter or environment directory
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,46 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Manage environments
Usage: pipdock env [OPTIONS] <COMMAND>
Commands:
list List discovered environments, their sources and PEP 668 flags
use Set the default environment
help Print this message or the help of the given subcommand(s)
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,50 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Run Code Health (deptry / vulture / ruff) over a project folder
Usage: pipdock health [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--path <DIR>
Project folder; defaults to the folder remembered for this environment
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--tool <TOOL>
Run a single tool instead of all three
--fix
Apply ruff's safe fixes. Prompts before writing
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,41 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[parent, child, \"--help\"])"
---
Re-pull the PEP 691 name index
Usage: pipdock index refresh [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,45 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Index maintenance
Usage: pipdock index [OPTIONS] <COMMAND>
Commands:
refresh Re-pull the PEP 691 name index
help Print this message or the help of the given subcommand(s)
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,45 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Show cached PyPI metadata for a package
Usage: pipdock info [OPTIONS] <PKG>
Arguments:
<PKG>
Package name
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,48 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Install packages
Usage: pipdock install [OPTIONS] <SPECS>...
Arguments:
<SPECS>...
`name` or `name==version`
Options:
--dry-run
Print the resolution report and exit without changing anything
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,44 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
List installed packages
Usage: pipdock list [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--outdated
Show only packages with a newer release available
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,48 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[parent, child, \"--help\"])"
---
Pin a package so bulk updates skip it
Usage: pipdock pin add [OPTIONS] <PKG>
Arguments:
<PKG>
Package name
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--reason <REASON>
Why it is pinned
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,41 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[parent, child, \"--help\"])"
---
Show the pin list
Usage: pipdock pin list [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,45 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[parent, child, \"--help\"])"
---
Remove a pin
Usage: pipdock pin remove [OPTIONS] <PKG>
Arguments:
<PKG>
Package name
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,47 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Manage the per-environment pin list
Usage: pipdock pin [OPTIONS] <COMMAND>
Commands:
add Pin a package so bulk updates skip it
remove Remove a pin
list Show the pin list
help Print this message or the help of the given subcommand(s)
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,41 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Upgrade pip inside the selected environment
Usage: pipdock pip-upgrade [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,45 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Print the JSON Schema for a core type so scripts can pin against it
Usage: pipdock schema [OPTIONS] <TYPE_NAME>
Arguments:
<TYPE_NAME>
Type name, e.g. `ResolutionReport`
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,50 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Fuzzy-search the local PyPI name index
Usage: pipdock search [OPTIONS] <QUERY>
Arguments:
<QUERY>
Query string
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--limit <LIMIT>
Maximum results
[default: 20]
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,41 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[parent, child, \"--help\"])"
---
Print a prefilled GitHub issue URL
Usage: pipdock self report-bug [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,45 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Self-service helpers
Usage: pipdock self [OPTIONS] <COMMAND>
Commands:
report-bug Print a prefilled GitHub issue URL
help Print this message or the help of the given subcommand(s)
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,41 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[parent, child, \"--help\"])"
---
Take a snapshot now
Usage: pipdock snapshot create [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,45 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[parent, child, \"--help\"])"
---
Diff a snapshot against the current environment
Usage: pipdock snapshot diff [OPTIONS] <ID>
Arguments:
<ID>
Snapshot id
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,41 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[parent, child, \"--help\"])"
---
List snapshots for the selected environment
Usage: pipdock snapshot list [OPTIONS]
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,45 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[parent, child, \"--help\"])"
---
Restore a snapshot
Usage: pipdock snapshot rollback [OPTIONS] <ID>
Arguments:
<ID>
Snapshot id, or `latest`
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,48 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Manage snapshots
Usage: pipdock snapshot [OPTIONS] <COMMAND>
Commands:
list List snapshots for the selected environment
create Take a snapshot now
diff Diff a snapshot against the current environment
rollback Restore a snapshot
help Print this message or the help of the given subcommand(s)
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,48 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Remove packages, guarded by the reverse-dependency check
Usage: pipdock uninstall [OPTIONS] <PKGS>...
Arguments:
<PKGS>...
Packages to remove
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--force
Proceed even when the guard reports dependents that would break
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,63 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[cmd, \"--help\"])"
---
Update packages
Usage: pipdock update [OPTIONS] [PKGS]...
Arguments:
[PKGS]...
Packages to update; omit and pass `--all` for everything
Options:
--all
Update every outdated package (pins still apply)
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--strategy <STRATEGY>
Conflict strategy
Possible values:
- compatible: Accept the resolver's compatible version. The safe default
- latest: Force the latest version. Off a TTY this requires an explicit acknowledgement
[default: compatible]
--except <PKG,...>
Ad-hoc exclusions on top of the pin list
--json
Machine-readable output; NDJSON for streaming commands
--dry-run
Print the resolution report and exit without changing anything
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
@@ -0,0 +1,64 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stdout_of(&[\"--help\"])"
---
Inspect, install, update and clean up Python packages in bulk.
Every mutating operation is previewed and snapshotted first.
Usage: pipdock [OPTIONS] <COMMAND>
Commands:
env Manage environments
list List installed packages
search Fuzzy-search the local PyPI name index
info Show cached PyPI metadata for a package
install Install packages
update Update packages
uninstall Remove packages, guarded by the reverse-dependency check
pin Manage the per-environment pin list
snapshot Manage snapshots
doctor Engine check and environment sanity report
health Run Code Health (deptry / vulture / ruff) over a project folder
pip-upgrade Upgrade pip inside the selected environment
engine Show or set the configured engine
index Index maintenance
schema Print the JSON Schema for a core type so scripts can pin against it
self Self-service helpers
help Print this message or the help of the given subcommand(s)
Options:
--env <PATH>
Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory
--engine <ENGINE>
Override the configured engine for this invocation
Possible values:
- pip: `<python> -m pip`
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
--quiet
Reduce log output
--verbose
Increase log output
--log-file <PATH>
Tee logs to a file
--no-snapshot
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.
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
@@ -0,0 +1,51 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$defs": {
"CheckFinding": {
"description": "One unsatisfied requirement reported by `pip check` / `uv pip check`.",
"properties": {
"pkg": {
"$ref": "#/$defs/PkgName",
"description": "The distribution whose requirement is unsatisfied."
},
"requirement": {
"description": "Human-readable requirement text as the engine printed it.",
"type": "string"
}
},
"required": [
"pkg",
"requirement"
],
"type": "object"
},
"PkgName": {
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Post-execution environment verification.",
"properties": {
"findings": {
"default": [],
"description": "Details when `ok` is false.",
"items": {
"$ref": "#/$defs/CheckFinding"
},
"type": "array"
},
"ok": {
"description": "True when the engine reported no broken requirements.",
"type": "boolean"
}
},
"required": [
"ok"
],
"title": "CheckReport",
"type": "object"
}
@@ -0,0 +1,161 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Every code PipDock can surface at v1 launch.\n\n`docs/TESTING.md` §2 requires at least one captured stderr fixture per variant before ship;\nthe test that enforces \"no code without fixture\" lives beside the classifiers.",
"oneOf": [
{
"const": "EnvInterpreterMissing",
"description": "Interpreter path missing or not executable — the env was deleted or moved.",
"type": "string"
},
{
"const": "EnvExternallyManaged",
"description": "PEP 668 `EXTERNALLY-MANAGED` marker present; mutation blocked by default.",
"type": "string"
},
{
"const": "EnvProbeFailed",
"description": "`probe.py` exited non-zero or produced unparseable output.",
"type": "string"
},
{
"const": "EngNotFound",
"description": "pip or uv binary not found.",
"type": "string"
},
{
"const": "EngPipTooOld",
"description": "pip older than 22.2, which predates `--dry-run --report`.",
"type": "string"
},
{
"const": "EngUvShapeUnknown",
"description": "uv emitted a shape the adapter does not recognize (uv newer than PipDock).",
"type": "string"
},
{
"const": "EngUnclassified",
"description": "Fallback for engine failures no classifier matched. Always last.",
"type": "string"
},
{
"const": "ResImpossible",
"description": "`ResolutionImpossible` or the uv equivalent: constraints cannot be satisfied.",
"type": "string"
},
{
"const": "ResPlanStale",
"description": "Plan older than 10 minutes, or the env's probe hash changed since the preview.",
"type": "string"
},
{
"const": "BldMsvcMissing",
"description": "MSVC build tools required but absent.",
"type": "string"
},
{
"const": "BldBackendFailed",
"description": "Build backend failed (`pyproject.toml` error, `metadata-generation-failed`).",
"type": "string"
},
{
"const": "BldWheelFailed",
"description": "Generic sdist wheel-build failure.",
"type": "string"
},
{
"const": "PkgRequiresPython",
"description": "No matching distribution, and metadata shows a requires-python mismatch.",
"type": "string"
},
{
"const": "PkgNotFound",
"description": "No matching distribution: name or version typo, or the release is gone.",
"type": "string"
},
{
"const": "PkgYanked",
"description": "The requested release was yanked.",
"type": "string"
},
{
"const": "PkgHashMismatch",
"description": "Downloaded artifact failed hash verification.",
"type": "string"
},
{
"const": "NetUnreachable",
"description": "Timeout, connection aborted, or DNS failure.",
"type": "string"
},
{
"const": "NetTlsFailure",
"description": "TLS/SSL verification failed — typically proxy or AV interception.",
"type": "string"
},
{
"const": "NetIndexRefreshFailed",
"description": "PEP 691 index refresh failed; the stale index stays searchable.",
"type": "string"
},
{
"const": "NetToolsBootstrapFailed",
"description": "Code Health tools-venv bootstrap could not reach PyPI.",
"type": "string"
},
{
"const": "PrmSitePackagesReadOnly",
"description": "`PermissionError` writing site-packages (admin-owned Python).",
"type": "string"
},
{
"const": "PrmFileLocked",
"description": "File locked by a running process (`WinError 32`).",
"type": "string"
},
{
"const": "SnpWriteFailed",
"description": "Snapshot write failed before execution. **The plan is aborted; nothing runs.**",
"type": "string"
},
{
"const": "SnpTargetUnavailable",
"description": "A release needed to restore a snapshot is no longer available on PyPI.",
"type": "string"
},
{
"const": "SysPathTooLong",
"description": "`MAX_PATH` exceeded without the long-path opt-in.",
"type": "string"
},
{
"const": "SysDiskFull",
"description": "Disk full.",
"type": "string"
},
{
"const": "HltToolMissing",
"description": "A Code Health tool is missing from the tools venv.",
"type": "string"
},
{
"const": "HltToolFailed",
"description": "A Code Health tool exited non-zero.",
"type": "string"
},
{
"const": "HltTimeout",
"description": "A Code Health tool exceeded its watchdog timeout; partial report shown.",
"type": "string"
},
{
"const": "IntUnexpected",
"description": "A PipDock bug: panic or unexpected state.",
"type": "string"
}
],
"title": "Code"
}
@@ -0,0 +1,89 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$defs": {
"ChangedEntry": {
"description": "One package whose version differs between two states.",
"properties": {
"current": {
"$ref": "#/$defs/Version",
"description": "What is installed now."
},
"name": {
"$ref": "#/$defs/PkgName",
"description": "The package."
},
"snapshot": {
"$ref": "#/$defs/Version",
"description": "What the snapshot recorded."
}
},
"required": [
"name",
"current",
"snapshot"
],
"type": "object"
},
"PinnedSpec": {
"description": "A resolved, exact `name==version` pair. Only these reach a mutating engine command.",
"properties": {
"name": {
"$ref": "#/$defs/PkgName",
"description": "Normalized distribution name."
},
"version": {
"$ref": "#/$defs/Version",
"description": "The exact version the resolver chose."
}
},
"required": [
"name",
"version"
],
"type": "object"
},
"PkgName": {
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
},
"Version": {
"description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "The difference between two environment states.",
"properties": {
"added": {
"description": "Present now, absent in the snapshot.",
"items": {
"$ref": "#/$defs/PinnedSpec"
},
"type": "array"
},
"changed": {
"description": "Present in both at different versions.",
"items": {
"$ref": "#/$defs/ChangedEntry"
},
"type": "array"
},
"removed": {
"description": "Present in the snapshot, absent now.",
"items": {
"$ref": "#/$defs/PinnedSpec"
},
"type": "array"
}
},
"required": [
"added",
"removed",
"changed"
],
"title": "Diff",
"type": "object"
}
@@ -0,0 +1,50 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$defs": {
"PkgName": {
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
},
"Version": {
"description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "An installed distribution, as read by `probe.py` or `<engine> list`.",
"properties": {
"name": {
"$ref": "#/$defs/PkgName",
"description": "Normalized distribution name."
},
"requires_dist": {
"default": [],
"description": "Raw `Requires-Dist` entries. The reverse-dependency graph is built from these.",
"items": {
"type": "string"
},
"type": "array"
},
"requires_python": {
"default": null,
"description": "Raw `Requires-Python` specifier, when declared.",
"type": [
"string",
"null"
]
},
"version": {
"$ref": "#/$defs/Version",
"description": "Installed version."
}
},
"required": [
"name",
"version"
],
"title": "Dist",
"type": "object"
}
@@ -0,0 +1,368 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$defs": {
"CheckFinding": {
"description": "One unsatisfied requirement reported by `pip check` / `uv pip check`.",
"properties": {
"pkg": {
"$ref": "#/$defs/PkgName",
"description": "The distribution whose requirement is unsatisfied."
},
"requirement": {
"description": "Human-readable requirement text as the engine printed it.",
"type": "string"
}
},
"required": [
"pkg",
"requirement"
],
"type": "object"
},
"CheckReport": {
"description": "Post-execution environment verification.",
"properties": {
"findings": {
"default": [],
"description": "Details when `ok` is false.",
"items": {
"$ref": "#/$defs/CheckFinding"
},
"type": "array"
},
"ok": {
"description": "True when the engine reported no broken requirements.",
"type": "boolean"
}
},
"required": [
"ok"
],
"type": "object"
},
"Code": {
"description": "Every code PipDock can surface at v1 launch.\n\n`docs/TESTING.md` §2 requires at least one captured stderr fixture per variant before ship;\nthe test that enforces \"no code without fixture\" lives beside the classifiers.",
"oneOf": [
{
"const": "EnvInterpreterMissing",
"description": "Interpreter path missing or not executable — the env was deleted or moved.",
"type": "string"
},
{
"const": "EnvExternallyManaged",
"description": "PEP 668 `EXTERNALLY-MANAGED` marker present; mutation blocked by default.",
"type": "string"
},
{
"const": "EnvProbeFailed",
"description": "`probe.py` exited non-zero or produced unparseable output.",
"type": "string"
},
{
"const": "EngNotFound",
"description": "pip or uv binary not found.",
"type": "string"
},
{
"const": "EngPipTooOld",
"description": "pip older than 22.2, which predates `--dry-run --report`.",
"type": "string"
},
{
"const": "EngUvShapeUnknown",
"description": "uv emitted a shape the adapter does not recognize (uv newer than PipDock).",
"type": "string"
},
{
"const": "EngUnclassified",
"description": "Fallback for engine failures no classifier matched. Always last.",
"type": "string"
},
{
"const": "ResImpossible",
"description": "`ResolutionImpossible` or the uv equivalent: constraints cannot be satisfied.",
"type": "string"
},
{
"const": "ResPlanStale",
"description": "Plan older than 10 minutes, or the env's probe hash changed since the preview.",
"type": "string"
},
{
"const": "BldMsvcMissing",
"description": "MSVC build tools required but absent.",
"type": "string"
},
{
"const": "BldBackendFailed",
"description": "Build backend failed (`pyproject.toml` error, `metadata-generation-failed`).",
"type": "string"
},
{
"const": "BldWheelFailed",
"description": "Generic sdist wheel-build failure.",
"type": "string"
},
{
"const": "PkgRequiresPython",
"description": "No matching distribution, and metadata shows a requires-python mismatch.",
"type": "string"
},
{
"const": "PkgNotFound",
"description": "No matching distribution: name or version typo, or the release is gone.",
"type": "string"
},
{
"const": "PkgYanked",
"description": "The requested release was yanked.",
"type": "string"
},
{
"const": "PkgHashMismatch",
"description": "Downloaded artifact failed hash verification.",
"type": "string"
},
{
"const": "NetUnreachable",
"description": "Timeout, connection aborted, or DNS failure.",
"type": "string"
},
{
"const": "NetTlsFailure",
"description": "TLS/SSL verification failed — typically proxy or AV interception.",
"type": "string"
},
{
"const": "NetIndexRefreshFailed",
"description": "PEP 691 index refresh failed; the stale index stays searchable.",
"type": "string"
},
{
"const": "NetToolsBootstrapFailed",
"description": "Code Health tools-venv bootstrap could not reach PyPI.",
"type": "string"
},
{
"const": "PrmSitePackagesReadOnly",
"description": "`PermissionError` writing site-packages (admin-owned Python).",
"type": "string"
},
{
"const": "PrmFileLocked",
"description": "File locked by a running process (`WinError 32`).",
"type": "string"
},
{
"const": "SnpWriteFailed",
"description": "Snapshot write failed before execution. **The plan is aborted; nothing runs.**",
"type": "string"
},
{
"const": "SnpTargetUnavailable",
"description": "A release needed to restore a snapshot is no longer available on PyPI.",
"type": "string"
},
{
"const": "SysPathTooLong",
"description": "`MAX_PATH` exceeded without the long-path opt-in.",
"type": "string"
},
{
"const": "SysDiskFull",
"description": "Disk full.",
"type": "string"
},
{
"const": "HltToolMissing",
"description": "A Code Health tool is missing from the tools venv.",
"type": "string"
},
{
"const": "HltToolFailed",
"description": "A Code Health tool exited non-zero.",
"type": "string"
},
{
"const": "HltTimeout",
"description": "A Code Health tool exceeded its watchdog timeout; partial report shown.",
"type": "string"
},
{
"const": "IntUnexpected",
"description": "A PipDock bug: panic or unexpected state.",
"type": "string"
}
]
},
"Counts": {
"description": "Aggregate counts rendered as \"13 successful, 2 failed, 1 skipped\" (DATA-FLOW §6).",
"properties": {
"failed": {
"description": "Steps that failed, each with a catalog code.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"ok": {
"description": "Steps that applied.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"skipped": {
"description": "Steps not attempted.",
"format": "uint",
"minimum": 0,
"type": "integer"
}
},
"required": [
"ok",
"failed",
"skipped"
],
"type": "object"
},
"ExecMode": {
"description": "Which of the two execution phases produced a result (ARCHITECTURE §8).",
"oneOf": [
{
"const": "batch",
"description": "Phase A: one engine invocation for the whole pinned set.",
"type": "string"
},
{
"const": "isolated",
"description": "Phase B: per-package sequential retry after Phase A failed. Skip-and-continue.",
"type": "string"
}
]
},
"PkgName": {
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
},
"StepResult": {
"description": "One row of the summary report (DATA-FLOW §6).",
"properties": {
"code": {
"anyOf": [
{
"$ref": "#/$defs/Code"
},
{
"type": "null"
}
],
"description": "Catalog code, present exactly when `status` is `Failed`."
},
"from": {
"anyOf": [
{
"$ref": "#/$defs/Version"
},
{
"type": "null"
}
],
"description": "Version before the step, absent for a fresh install."
},
"pkg": {
"$ref": "#/$defs/PkgName",
"description": "Normalized distribution name."
},
"status": {
"$ref": "#/$defs/StepStatus",
"description": "Whether it applied."
},
"stderr_tail": {
"description": "Tail of the engine's stderr for the failure detail pane.",
"type": [
"string",
"null"
]
},
"to": {
"anyOf": [
{
"$ref": "#/$defs/Version"
},
{
"type": "null"
}
],
"description": "Version the step targeted."
}
},
"required": [
"pkg",
"status"
],
"type": "object"
},
"StepStatus": {
"description": "Outcome of a single package's step.",
"oneOf": [
{
"const": "ok",
"description": "Applied successfully.",
"type": "string"
},
{
"const": "failed",
"description": "Failed; carries a catalog code. Does **not** abort the batch.",
"type": "string"
},
{
"const": "skipped",
"description": "Not attempted — user cancelled, or dropped by a Skip decision.",
"type": "string"
}
]
},
"Version": {
"description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "The end-of-run report shown in the summary sheet and emitted by `--json`.",
"properties": {
"check": {
"$ref": "#/$defs/CheckReport",
"description": "Post-run `engine.check()`."
},
"counts": {
"$ref": "#/$defs/Counts",
"description": "Derived from `results`; see [`ExecutionSummary::tally`]."
},
"phase": {
"$ref": "#/$defs/ExecMode",
"description": "Which phase produced these results."
},
"plan_id": {
"description": "Correlates the summary with its snapshot and log ring buffer.",
"type": "string"
},
"results": {
"default": [],
"description": "One row per package.",
"items": {
"$ref": "#/$defs/StepResult"
},
"type": "array"
}
},
"required": [
"plan_id",
"phase",
"check",
"counts"
],
"title": "ExecutionSummary",
"type": "object"
}
@@ -0,0 +1,47 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$defs": {
"PkgName": {
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "What the uninstall guard found.\n\nRationale from DATA-FLOW §5: bare `pip uninstall` performs **no** dependency check at all, so\nthis is a core value-add rather than a nicety. It is computed once against the full set,\nbecause removing A and B together is fine when only B depends on A — asking per package would\nraise a warning the user cannot act on.",
"properties": {
"breaks": {
"additionalProperties": {
"items": {
"$ref": "#/$defs/PkgName"
},
"type": "array"
},
"description": "For each package that has them, the installed packages that would break.",
"type": "object"
},
"removing": {
"description": "The set the user asked to remove.",
"items": {
"$ref": "#/$defs/PkgName"
},
"type": "array"
},
"with_dependents": {
"description": "The removal set expanded to include everything that depends on it, transitively — the\n\"remove dependents too\" option.",
"items": {
"$ref": "#/$defs/PkgName"
},
"type": "array"
}
},
"required": [
"removing",
"breaks",
"with_dependents"
],
"title": "GuardReport",
"type": "object"
}
@@ -0,0 +1,55 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$defs": {
"MatchKind": {
"description": "How a hit matched, in ranking order.",
"oneOf": [
{
"const": "exact",
"description": "The query is the name.",
"type": "string"
},
{
"const": "prefix",
"description": "The name starts with the query.",
"type": "string"
},
{
"const": "fuzzy",
"description": "The query appears in the name, in order but not contiguously.",
"type": "string"
}
]
},
"PkgName": {
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "One search result.",
"properties": {
"display": {
"description": "The name as PyPI spells it, for display.",
"type": "string"
},
"kind": {
"$ref": "#/$defs/MatchKind",
"description": "Why it ranked where it did. Exposed so the UI can group exact and prefix matches visually."
},
"name": {
"$ref": "#/$defs/PkgName",
"description": "The normalized name, which is what every other module keys on."
}
},
"required": [
"name",
"display",
"kind"
],
"title": "Hit",
"type": "object"
}
@@ -0,0 +1,39 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$defs": {
"PkgName": {
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
},
"Version": {
"description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "An installed distribution with a newer release available.",
"properties": {
"current": {
"$ref": "#/$defs/Version",
"description": "Currently installed version."
},
"latest": {
"$ref": "#/$defs/Version",
"description": "Newest version the index offers."
},
"name": {
"$ref": "#/$defs/PkgName",
"description": "Normalized distribution name."
}
},
"required": [
"name",
"current",
"latest"
],
"title": "OutdatedDist",
"type": "object"
}
@@ -0,0 +1,54 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Cached PyPI metadata for one package (ARCHITECTURE §5).",
"properties": {
"home_page": {
"description": "Project home page, when declared.",
"type": [
"string",
"null"
]
},
"license": {
"description": "License text or identifier.",
"type": [
"string",
"null"
]
},
"name": {
"description": "Normalized name.",
"type": "string"
},
"requires_python": {
"description": "`Requires-Python` specifier.",
"type": [
"string",
"null"
]
},
"summary": {
"description": "One-line description.",
"type": [
"string",
"null"
]
},
"version": {
"description": "Newest release.",
"type": [
"string",
"null"
]
}
},
"required": [
"name"
],
"title": "PackageMeta",
"type": "object"
}
@@ -0,0 +1,73 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$defs": {
"PinMode": {
"description": "How a pin constrains a package.",
"oneOf": [
{
"const": "exclude",
"description": "Excluded from bulk updates. The user can still update it deliberately, one package at a\ntime — a pin is \"do not sweep this up\", not \"never touch this\".",
"type": "string"
},
{
"additionalProperties": false,
"description": "Held at an exact version: excluded from bulk updates *and* restated at this version in\nevery plan, so the resolver treats it as fixed.",
"properties": {
"hold": {
"properties": {
"version": {
"$ref": "#/$defs/Version",
"description": "The version to hold at."
}
},
"required": [
"version"
],
"type": "object"
}
},
"required": [
"hold"
],
"type": "object"
}
]
},
"PkgName": {
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
},
"Version": {
"description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "A pin with the reason the user gave for it.",
"properties": {
"mode": {
"$ref": "#/$defs/PinMode",
"description": "How it is constrained."
},
"pkg": {
"$ref": "#/$defs/PkgName",
"description": "The pinned package."
},
"reason": {
"description": "Free-text justification shown in the Pins screen.\n\nWorth storing even though nothing reads it programmatically: a pin without a reason\nbecomes a mystery the user is afraid to remove, and so stays forever.",
"type": [
"string",
"null"
]
}
},
"required": [
"pkg",
"mode"
],
"title": "Pin",
"type": "object"
}
@@ -0,0 +1,96 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$defs": {
"PkgName": {
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
},
"Spec": {
"description": "What the user asked for: a name, optionally constrained.",
"properties": {
"name": {
"$ref": "#/$defs/PkgName",
"description": "Normalized distribution name."
},
"version_req": {
"description": "PEP 440 specifier such as `\">=2,<3\"`, or `None` for \"latest\".",
"type": [
"string",
"null"
]
}
},
"required": [
"name"
],
"type": "object"
},
"Strategy": {
"description": "How aggressively to resolve conflicts.",
"oneOf": [
{
"const": "compatible",
"description": "Accept whatever the resolver can satisfy. The safe default; `[C]ompatible` in the CLI.",
"type": "string"
},
{
"additionalProperties": false,
"description": "Force the latest version of the listed packages even though it violates another\npackage's requirement. The UI must name what breaks before this is selectable\n(UI-SPEC §4, DISCLAIMER §2).",
"properties": {
"force-latest": {
"properties": {
"overrides": {
"description": "Only these packages are forced; everything else stays `Compatible`.",
"items": {
"$ref": "#/$defs/PkgName"
},
"type": "array"
}
},
"required": [
"overrides"
],
"type": "object"
}
},
"required": [
"force-latest"
],
"type": "object"
}
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "The user's intent, before the engine has said anything about it.",
"properties": {
"installs": {
"default": [],
"description": "New packages queued in the dock bay.",
"items": {
"$ref": "#/$defs/Spec"
},
"type": "array"
},
"strategy": {
"$ref": "#/$defs/Strategy",
"description": "Conflict-handling strategy."
},
"upgrades": {
"default": [],
"description": "Already-installed packages the user selected for upgrade.",
"items": {
"$ref": "#/$defs/PkgName"
},
"type": "array"
}
},
"required": [
"strategy"
],
"title": "PlanRequest",
"type": "object"
}
@@ -0,0 +1,79 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$defs": {
"EnvSource": {
"description": "How an environment was discovered. Surfaced as the source chip in the Environments screen.",
"oneOf": [
{
"const": "registry",
"description": "PEP 514 registry entry.",
"type": "string"
},
{
"const": "py-launcher",
"description": "Reported by the `py` launcher (`py -0p`).",
"type": "string"
},
{
"const": "uv",
"description": "Reported by `uv python list`.",
"type": "string"
},
{
"const": "venv-scan",
"description": "Found by scanning known venv directories.",
"type": "string"
},
{
"const": "manual",
"description": "Added by the user via *Browse…*.",
"type": "string"
}
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "A Python environment PipDock can act on.",
"properties": {
"externally_managed": {
"description": "PEP 668 marker present. When true, mutation is blocked unless the user enabled the\nSettings override (`PD-ENV-002`, SECURITY §3).",
"type": "boolean"
},
"hidden_user_site": {
"default": null,
"description": "User site-packages directory that `probe.py -I` is hiding, when there is one.\n\nOwner decision 2026-07-27 (SP-6): the probe keeps running isolated, so on a non-venv\nsystem Python it reports fewer distributions than `pip list` does. `Some` means packages\nreally are hidden and the Installed screen shows a note naming this path; `None` — always\nthe case inside a venv — means the listing is complete.",
"type": [
"string",
"null"
]
},
"interpreter": {
"description": "Canonicalized path to the interpreter. Never a shell string — see SECURITY §2.",
"type": "string"
},
"prefix": {
"description": "`sys.prefix` as reported by `probe.py`.",
"type": "string"
},
"python_version": {
"description": "e.g. `\"3.12.4\"`.",
"type": "string"
},
"source": {
"$ref": "#/$defs/EnvSource",
"description": "Where this env came from."
}
},
"required": [
"interpreter",
"prefix",
"python_version",
"externally_managed",
"source"
],
"title": "PyEnv",
"type": "object"
}
@@ -0,0 +1,191 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$defs": {
"Blocker": {
"description": "The package responsible for holding another one back.\n\nARCHITECTURE §3: the engine's report says *what* was held back; *who* is responsible comes from\ncross-referencing the reverse-dependency graph with each blocker's `Requires-Dist` constraint.\n**If attribution is ambiguous, show the constraint without a culprit rather than guessing.**",
"properties": {
"by": {
"anyOf": [
{
"$ref": "#/$defs/PkgName"
},
{
"type": "null"
}
],
"description": "The package imposing the constraint, absent when attribution is ambiguous."
},
"constraint": {
"description": "The constraint text, e.g. `\"requests<2.31\"`.",
"type": "string"
}
},
"required": [
"constraint"
],
"type": "object"
},
"Change": {
"description": "One line of the preview diff.",
"properties": {
"from": {
"anyOf": [
{
"$ref": "#/$defs/Version"
},
{
"type": "null"
}
],
"description": "Version before, absent for a fresh install."
},
"kind": {
"$ref": "#/$defs/ChangeKind",
"description": "Which preview section this belongs in."
},
"name": {
"$ref": "#/$defs/PkgName",
"description": "Normalized distribution name."
},
"to": {
"$ref": "#/$defs/Version",
"description": "Version the resolver chose."
}
},
"required": [
"name",
"to",
"kind"
],
"type": "object"
},
"ChangeKind": {
"description": "Which section of the preview a change belongs to (UI-SPEC §4).",
"oneOf": [
{
"const": "upgrade",
"description": "An installed package moving to a newer version.",
"type": "string"
},
{
"const": "new-dependency",
"description": "A package pulled in to satisfy something else.",
"type": "string"
},
{
"const": "new-install",
"description": "A package the user explicitly asked to install.",
"type": "string"
},
{
"const": "downgrade",
"description": "A package moving to an older version to satisfy a constraint.",
"type": "string"
}
]
},
"HeldBack": {
"description": "A package the resolver could not take all the way to `latest`.",
"properties": {
"blockers": {
"default": [],
"description": "Why it could not go further. Empty means the engine gave no attributable reason.",
"items": {
"$ref": "#/$defs/Blocker"
},
"type": "array"
},
"latest": {
"$ref": "#/$defs/Version",
"description": "The version the index offers."
},
"pkg": {
"$ref": "#/$defs/PkgName",
"description": "Normalized distribution name."
},
"resolved": {
"$ref": "#/$defs/Version",
"description": "The version the resolver settled on."
}
},
"required": [
"pkg",
"resolved",
"latest"
],
"type": "object"
},
"ImpossibleDetail": {
"description": "A `ResolutionImpossible` outcome and whatever detail the engine gave (`PD-RES-001`).",
"properties": {
"explanation": {
"description": "The engine's own explanation, verbatim.",
"type": "string"
},
"packages": {
"default": [],
"description": "Packages involved in the unsatisfiable set.",
"items": {
"$ref": "#/$defs/PkgName"
},
"type": "array"
}
},
"required": [
"explanation"
],
"type": "object"
},
"PkgName": {
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
},
"Version": {
"description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "The normalized dry-run result.\n\n**Both adapters must emit this same shape** — that is the whole point of the `Engine` trait\n(ARCHITECTURE §3). The pip adapter fills it from `--dry-run --report` JSON; the uv adapter from\nuv's text plan output.\n\nThe exact field set is **provisional until spike SP-1** confirms uv's output is rich enough to\npopulate `held_back.blockers`. If it is not, SP-1's go/no-go says v1.0 ships pip-primary with uv\nbehind a beta flag.",
"properties": {
"changes": {
"default": [],
"description": "Everything that would change if the user confirms.",
"items": {
"$ref": "#/$defs/Change"
},
"type": "array"
},
"held_back": {
"default": [],
"description": "Packages that could not reach `latest`, with attribution.",
"items": {
"$ref": "#/$defs/HeldBack"
},
"type": "array"
},
"impossible": {
"anyOf": [
{
"$ref": "#/$defs/ImpossibleDetail"
},
{
"type": "null"
}
],
"description": "Present when the whole resolution failed."
},
"raw": {
"description": "The engine's untouched output, kept for the log and for bug reports.",
"type": "string"
}
},
"required": [
"raw"
],
"title": "ResolutionReport",
"type": "object"
}
@@ -0,0 +1,117 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$defs": {
"EngineId": {
"description": "Which resolver PipDock is driving.",
"oneOf": [
{
"const": "pip",
"description": "`<python> -m pip …`",
"type": "string"
},
{
"const": "uv",
"description": "`uv pip … --python <python>`",
"type": "string"
}
]
},
"Trigger": {
"description": "What caused a snapshot to be taken. Shown as the trigger label on the timeline (UI-SPEC §4).",
"oneOf": [
{
"additionalProperties": false,
"description": "Taken automatically before a plan executed.",
"properties": {
"plan": {
"properties": {
"plan_id": {
"description": "The plan's id, so a summary and its snapshot can be tied together.",
"type": "string"
}
},
"required": [
"plan_id"
],
"type": "object"
}
},
"required": [
"plan"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Taken automatically before a rollback, because a rollback is itself reversible\n(DATA-FLOW §8).",
"properties": {
"rollback": {
"properties": {
"restoring": {
"description": "The snapshot being restored.",
"type": "string"
}
},
"required": [
"restoring"
],
"type": "object"
}
},
"required": [
"rollback"
],
"type": "object"
},
{
"const": "manual",
"description": "Taken because the user asked.",
"type": "string"
}
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "The `.meta.json` sidecar (ARCHITECTURE §6).",
"properties": {
"app_version": {
"description": "PipDock's version, so an old snapshot can be interpreted by a newer build.",
"type": "string"
},
"created_at": {
"description": "When it was taken, RFC 3339.",
"type": "string"
},
"engine": {
"$ref": "#/$defs/EngineId",
"description": "Which engine produced the freeze.\n\nLoad-bearing: pip freezes with `--all` and includes pip/setuptools, uv has no such flag and\nomits them (DATA-FLOW §7). Without this, a diff across engines would read as \"pip was\nuninstalled\"."
},
"id": {
"description": "Snapshot id, which is also its filename stem.",
"type": "string"
},
"package_count": {
"description": "How many distributions the freeze recorded.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"trigger": {
"$ref": "#/$defs/Trigger",
"description": "Why it was taken."
}
},
"required": [
"id",
"created_at",
"trigger",
"engine",
"package_count",
"app_version"
],
"title": "Meta",
"type": "object"
}
@@ -0,0 +1,249 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: out
---
{
"$defs": {
"Code": {
"description": "Every code PipDock can surface at v1 launch.\n\n`docs/TESTING.md` §2 requires at least one captured stderr fixture per variant before ship;\nthe test that enforces \"no code without fixture\" lives beside the classifiers.",
"oneOf": [
{
"const": "EnvInterpreterMissing",
"description": "Interpreter path missing or not executable — the env was deleted or moved.",
"type": "string"
},
{
"const": "EnvExternallyManaged",
"description": "PEP 668 `EXTERNALLY-MANAGED` marker present; mutation blocked by default.",
"type": "string"
},
{
"const": "EnvProbeFailed",
"description": "`probe.py` exited non-zero or produced unparseable output.",
"type": "string"
},
{
"const": "EngNotFound",
"description": "pip or uv binary not found.",
"type": "string"
},
{
"const": "EngPipTooOld",
"description": "pip older than 22.2, which predates `--dry-run --report`.",
"type": "string"
},
{
"const": "EngUvShapeUnknown",
"description": "uv emitted a shape the adapter does not recognize (uv newer than PipDock).",
"type": "string"
},
{
"const": "EngUnclassified",
"description": "Fallback for engine failures no classifier matched. Always last.",
"type": "string"
},
{
"const": "ResImpossible",
"description": "`ResolutionImpossible` or the uv equivalent: constraints cannot be satisfied.",
"type": "string"
},
{
"const": "ResPlanStale",
"description": "Plan older than 10 minutes, or the env's probe hash changed since the preview.",
"type": "string"
},
{
"const": "BldMsvcMissing",
"description": "MSVC build tools required but absent.",
"type": "string"
},
{
"const": "BldBackendFailed",
"description": "Build backend failed (`pyproject.toml` error, `metadata-generation-failed`).",
"type": "string"
},
{
"const": "BldWheelFailed",
"description": "Generic sdist wheel-build failure.",
"type": "string"
},
{
"const": "PkgRequiresPython",
"description": "No matching distribution, and metadata shows a requires-python mismatch.",
"type": "string"
},
{
"const": "PkgNotFound",
"description": "No matching distribution: name or version typo, or the release is gone.",
"type": "string"
},
{
"const": "PkgYanked",
"description": "The requested release was yanked.",
"type": "string"
},
{
"const": "PkgHashMismatch",
"description": "Downloaded artifact failed hash verification.",
"type": "string"
},
{
"const": "NetUnreachable",
"description": "Timeout, connection aborted, or DNS failure.",
"type": "string"
},
{
"const": "NetTlsFailure",
"description": "TLS/SSL verification failed — typically proxy or AV interception.",
"type": "string"
},
{
"const": "NetIndexRefreshFailed",
"description": "PEP 691 index refresh failed; the stale index stays searchable.",
"type": "string"
},
{
"const": "NetToolsBootstrapFailed",
"description": "Code Health tools-venv bootstrap could not reach PyPI.",
"type": "string"
},
{
"const": "PrmSitePackagesReadOnly",
"description": "`PermissionError` writing site-packages (admin-owned Python).",
"type": "string"
},
{
"const": "PrmFileLocked",
"description": "File locked by a running process (`WinError 32`).",
"type": "string"
},
{
"const": "SnpWriteFailed",
"description": "Snapshot write failed before execution. **The plan is aborted; nothing runs.**",
"type": "string"
},
{
"const": "SnpTargetUnavailable",
"description": "A release needed to restore a snapshot is no longer available on PyPI.",
"type": "string"
},
{
"const": "SysPathTooLong",
"description": "`MAX_PATH` exceeded without the long-path opt-in.",
"type": "string"
},
{
"const": "SysDiskFull",
"description": "Disk full.",
"type": "string"
},
{
"const": "HltToolMissing",
"description": "A Code Health tool is missing from the tools venv.",
"type": "string"
},
{
"const": "HltToolFailed",
"description": "A Code Health tool exited non-zero.",
"type": "string"
},
{
"const": "HltTimeout",
"description": "A Code Health tool exceeded its watchdog timeout; partial report shown.",
"type": "string"
},
{
"const": "IntUnexpected",
"description": "A PipDock bug: panic or unexpected state.",
"type": "string"
}
]
},
"PkgName": {
"description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.",
"type": "string"
},
"StepStatus": {
"description": "Outcome of a single package's step.",
"oneOf": [
{
"const": "ok",
"description": "Applied successfully.",
"type": "string"
},
{
"const": "failed",
"description": "Failed; carries a catalog code. Does **not** abort the batch.",
"type": "string"
},
{
"const": "skipped",
"description": "Not attempted — user cancelled, or dropped by a Skip decision.",
"type": "string"
}
]
},
"Version": {
"description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "One row of the summary report (DATA-FLOW §6).",
"properties": {
"code": {
"anyOf": [
{
"$ref": "#/$defs/Code"
},
{
"type": "null"
}
],
"description": "Catalog code, present exactly when `status` is `Failed`."
},
"from": {
"anyOf": [
{
"$ref": "#/$defs/Version"
},
{
"type": "null"
}
],
"description": "Version before the step, absent for a fresh install."
},
"pkg": {
"$ref": "#/$defs/PkgName",
"description": "Normalized distribution name."
},
"status": {
"$ref": "#/$defs/StepStatus",
"description": "Whether it applied."
},
"stderr_tail": {
"description": "Tail of the engine's stderr for the failure detail pane.",
"type": [
"string",
"null"
]
},
"to": {
"anyOf": [
{
"$ref": "#/$defs/Version"
},
{
"type": "null"
}
],
"description": "Version the step targeted."
}
},
"required": [
"pkg",
"status"
],
"title": "StepResult",
"type": "object"
}
@@ -0,0 +1,5 @@
---
source: crates/pipdock-cli/tests/golden.rs
expression: "stderr_of(&[\"schema\", \"NoSuchType\"])"
---
error[PD-PKG-002]: unknown type "NoSuchType"; known types: Dist, OutdatedDist, PyEnv, CheckReport, StepResult, PlanRequest, ResolutionReport, ExecutionSummary, Pin, GuardReport, Diff, SnapshotMeta, Hit, PackageMeta, Code