fix: what installing the build found, and what the doc pass turned up

The release build was installed and driven before tagging. Two defects showed up that no suite
could see:
- Every dialog opened in the window's top-left corner. Tailwind's preflight sets `margin: 0` on
  everything, which removes the `margin: auto` a modal <dialog> is centred by; PdDialog (and so the
  uninstall guard, since it was written) and the Ctrl+K palette were both affected. `m-auto` /
  `mx-auto`, measured in the dev server: (0,0) before, centred after.
- On a profile that had never downloaded the index, Search said "preparing the package index"
  for ever and never offered the download. Moving the load into the background let a failed load
  restart on the next search, which reset the slot to Warming before the failure could be read,
  and the screen asked again every 150 ms. A failed load now stays failed until a refresh; a test
  in state.rs failed first against the old rule.

From the documentation pass, each checked against the code:
- The GUI's snapshot diff used the plain diff while the CLI's and the rollback used the
  engine-aware one, so the two heads disagreed about pip and setuptools across engines (G5).
- `--json`'s help still promised NDJSON; `--yes`, `--quiet`, `--verbose`, `--log-file`, the
  install spec and `engine` described behaviour they did not have. Corrected, and the 32 help
  goldens re-blessed for exactly those lines. `pipdock engine` now marks the configured engine,
  as its help always said; `health --fix` printed a dirty-tree warning to stdout before its JSON;
  the text preview now lists withdrawn releases, as the GUI's does.
- Copy that promised what the code does not do: a pinned package "can still be updated on its
  own" (an Exclude pin filters a named package too), a held pin left only "out of bulk updates",
  and an empty Environments screen pointing at a Browse… button that does not exist.
- Stale comments in exec, the pip and uv parsers, index refresh, health, the pin screen, the
  status line, the settings store and i18n.ts (whose missing-key warning never fires). The
  ExecutionSummary.cancelled description is part of the public schema, so that golden and the
  TypeScript bindings move with it.
- Metadata lookups reuse the shared HTTP client (M37 had been half done); insta was a dev
  dependency of core that nothing in core used; the integration workflow's checkouts no longer
  persist credentials; the capability file cites SECURITY §4, where the rule lives.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 committed 2026-10-17 00:55:27 +07:00
1 parent 310436552c
commit 42f227c1aa
60 files changed
+401 -230

No files matched your search

+4
View File
@@ -82,6 +82,8 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v7
with:
persist-credentials: false
- name: Setup Python ${{ matrix.python }}
uses: actions/setup-python@v7
@@ -399,6 +401,8 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v7
with:
persist-credentials: false
# An exact patch, on purpose. pip's report records `python_full_version` and uv prints "Using
# Python 3.12.x environment", so a floating `3.12` turns every runner-image Python bump into
Generated
-2
View File
@@ -2238,7 +2238,6 @@ dependencies = [
"console",
"once_cell",
"regex",
"serde",
"similar",
"strip-ansi-escapes",
"tempfile",
@@ -3239,7 +3238,6 @@ name = "pipdock-core"
version = "1.3.0"
dependencies = [
"async-trait",
"insta",
"jiff",
"nucleo",
"reqwest",
+12 -8
View File
@@ -99,23 +99,27 @@ pub struct GlobalOpts {
#[arg(long, global = true, value_enum)]
pub engine: Option<EngineArg>,
/// Machine-readable output; NDJSON for streaming commands.
/// Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
///
/// Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming
/// commands" until 1.4.0, when several commands printed several documents.
#[arg(long, global = true)]
pub json: bool,
/// Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*.
/// Assume the default at every prompt: a held-back package keeps its compatible version and
/// an impossible one is skipped. Only `--strategy latest` forces.
#[arg(long, short = 'y', global = true)]
pub yes: bool,
/// Reduce log output.
/// Do not stream engine output to stderr. (The log file is written regardless.)
#[arg(long, global = true, conflicts_with = "verbose")]
pub quiet: bool,
/// Increase log output.
/// Also write the log to stderr, at debug level.
#[arg(long, global = true)]
pub verbose: bool,
/// Tee logs to a file.
/// Also write the log to this file. The daily log in `data\logs\` is always kept.
#[arg(long, global = true, value_name = "PATH")]
pub log_file: Option<PathBuf>,
@@ -174,7 +178,7 @@ enum Command {
/// Install packages.
Install {
/// `name` or `name==version`.
/// A name with an optional PEP 440 specifier: `six`, `six==1.16.0`, `"six>=1.16,<2"`.
#[arg(required = true)]
specs: Vec<String>,
/// Print the resolution report and exit without changing anything.
@@ -246,7 +250,7 @@ enum Command {
/// Show or set the configured engine.
Engine {
/// Engine to switch to; omit to print the current one.
/// Engine to switch to; omit to list both, with versions, marking the configured one.
engine: Option<EngineArg>,
},
@@ -503,7 +507,7 @@ mod tests {
"--yes",
"--json",
"--log-file",
r"C:\logs\pd.json",
r"C:\logs\pd.log",
])
.expect("nightly maintenance example");
+32 -9
View File
@@ -26,10 +26,10 @@ use pipdock_core::{health, index, pins, plan, report, settings, snapshot};
use crate::{EngineArg, Exit, GlobalOpts, ToolArg};
/// Resolve which engine to drive.
/// Resolve which engine to drive: `--engine` for one invocation, else the configured one.
///
/// ARCHITECTURE §3: first run probes `uv --version` on PATH and preselects uv when present. The
/// `--engine` flag overrides for one invocation.
/// ARCHITECTURE §3 describes a first run that probes for uv and preselects it; neither head does
/// that yet (Audit backlog X19), and this deliberately does not — see the comment below.
#[must_use]
pub fn engine_for(opts: &GlobalOpts) -> Box<dyn Engine> {
let id = match opts.engine {
@@ -963,6 +963,16 @@ fn preview_text(report: &plan::ResolutionReport) -> String {
}
}
}
if !report.yanked.is_empty() {
// PD-PKG-003 is a warning, not a failure (SP-2). Shown in JSON only until 1.4.0.
line!("\nWithdrawn releases (yanked):");
for y in &report.yanked {
match &y.reason {
Some(reason) => line!(" {} {} — {reason}", y.pkg, y.version),
None => line!(" {} {}", y.pkg, y.version),
}
}
}
if let Some(detail) = &report.impossible {
line!("\nImpossible:");
line!(" {}", detail.explanation);
@@ -1086,8 +1096,8 @@ pub async fn tools_sync(opts: &GlobalOpts, force: bool, python: Option<&Path>) -
}
});
// A fresh token nothing trips, matching every other CLI path: the CLI installs no Ctrl-C
// handler, and the flows build their own tokens for the GUI's `plan_cancel` to reach. Killing
// A fresh token nothing trips: only the mutating commands install a Ctrl-C handler, and a
// sync is not one of them, so Ctrl-C ends the process and the sync with it. Killing
// the process still tears the tree down — `exec::TreeGuard`'s job object closes with the last
// handle — which is verified rather than assumed: a killed sync leaves no orphan pip.
let sink = engine::ProgressSink::new(
@@ -1383,8 +1393,10 @@ pub async fn health(
/// `--yes` means "assume defaults", and **the default over uncommitted work is don't**. A clean
/// tree proceeds: one `git checkout .` puts it back, so an unattended fix there is recoverable,
/// and refusing would make `--fix` useless in the pre-commit hook the exit-code rule was written
/// for. A dirty tree — or no repository at all — refuses with exit 2, because those are the cases
/// where a script could destroy work with no way back.
/// for. A dirty tree refuses with exit 2, because that is where a script could destroy work with
/// no way back. **Outside a repository `--yes` proceeds**: `fix::dirty` answers `None` both for a
/// clean tree and for no repository, so the two cannot be told apart here. Refusing there too is in
/// ROADMAP's Audit backlog; this comment used to claim it already did.
///
/// The escape hatch is deliberately **not a flag**. It is `git commit` or `git stash`, which is the
/// actual remedy and leaves the user something to return to; a `--force-fix` would exist only to be
@@ -1429,7 +1441,8 @@ async fn apply_fix(
true
} else if interactive {
if let Some(tree) = dirty {
println!(
// stderr, with the prompt it introduces: under `--json` stdout carries one document.
eprintln!(
"\n{} uncommitted change(s) in this repository. PipDock cannot undo a fix, and \
`git checkout .` would take your own edits with it.",
tree.entries
@@ -2202,13 +2215,23 @@ pub async fn engine_status(opts: &GlobalOpts) -> Result<Exit> {
print_json(&[&pip, &uv]);
return Ok(Exit::Success);
}
// The help has always said this command shows the current engine; it listed both and never
// said which one PipDock would use.
let configured = Store::open(&app_data_dir())
.and_then(|store| settings::load(&store))
.map_or(EngineId::Pip, |s| s.engine);
for info in [&pip, &uv] {
let detail = match (&info.version, info.id, &env) {
(Some(v), _, _) => v.clone(),
(None, EngineId::Pip, None) => "no environment selected".to_owned(),
(None, _, _) => "not available".to_owned(),
};
println!("{:<4} {detail}", info.id.as_str());
let mark = if info.id == configured {
" (configured)"
} else {
""
};
println!("{:<4} {detail}{mark}", info.id.as_str());
}
Ok(Exit::Success)
}
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,7 +8,7 @@ Usage: pipdock engine [OPTIONS] [ENGINE]
Arguments:
[ENGINE]
Engine to switch to; omit to print the current one
Engine to switch to; omit to list both, with versions, marking the configured one
Possible values:
- pip: `<python> -m pip`
@@ -19,19 +19,21 @@ Options:
Interpreter or environment directory. Defaults to the one `env use` set, else an auto-detected `.venv` in the working directory
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -23,19 +23,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -32,19 +32,21 @@ Options:
Apply ruff's safe fixes. Prompts before writing
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -8,7 +8,7 @@ Usage: pipdock install [OPTIONS] <SPECS>...
Arguments:
<SPECS>...
`name` or `name==version`
A name with an optional PEP 440 specifier: `six`, `six==[VERSION]`, `"six>=1.16,<2"`
Options:
--dry-run
@@ -25,19 +25,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -21,19 +21,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -25,19 +25,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -24,19 +24,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -27,19 +27,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -22,19 +22,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -25,19 +25,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -18,19 +18,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -24,19 +24,21 @@ Options:
Build on this interpreter instead of the newest discovered one
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -23,19 +23,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -25,19 +25,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -37,22 +37,24 @@ Options:
Ad-hoc exclusions on top of the pin list
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
--dry-run
Print the resolution report and exit without changing anything
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -40,19 +40,21 @@ Options:
- uv: `uv pip --python <python>`
--json
Machine-readable output; NDJSON for streaming commands
Machine-readable output: exactly one JSON document on stdout (CLI-SPEC §6).
Prompts, warnings and engine output go to stderr. This said "NDJSON for streaming commands" until [VERSION], when several commands printed several documents.
-y, --yes
Assume defaults on all prompts. Conflicts resolve to *skip*, never *force*
Assume the default at every prompt: a held-back package keeps its compatible version and an impossible one is skipped. Only `--strategy latest` forces
--quiet
Reduce log output
Do not stream engine output to stderr. (The log file is written regardless.)
--verbose
Increase log output
Also write the log to stderr, at debug level
--log-file <PATH>
Tee logs to a file
Also write the log to this file. The daily log in `data\logs\` is always kept
--no-snapshot
DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning.
@@ -370,7 +370,7 @@ expression: out
"properties": {
"cancelled": {
"default": false,
"description": "True when the user stopped this run part-way.\n\nARCHITECTURE §7 words this as `Skipped(UserCancelled)`, but [`StepStatus`] is a\npayload-free enum and giving it one changes the wire shape for every consumer. A flag on\nthe summary also matches what the summary sheet actually needs: \"cancelled\" is said once\nat the top, not repeated on forty rows.\n\nSteps that never ran are `Skipped`, which is already the honest status for them.",
"description": "True when the user stopped this run part-way.\n\nDATA-FLOW §3 used to word this as `Skipped(UserCancelled)`, but [`StepStatus`] is a\npayload-free enum and giving it one changes the wire shape for every consumer. A flag on\nthe summary also matches what the summary sheet actually needs: \"cancelled\" is said once\nat the top, not repeated on forty rows.\n\nSteps that never ran are `Skipped`, which is already the honest status for them.",
"type": "boolean"
},
"check": {
-1
View File
@@ -34,7 +34,6 @@ tokio-util = "0.7.20"
tracing = "0.1.44"
[dev-dependencies]
insta = { version = "1.49.0", features = ["json"] }
jiff = "0.2.38"
tokio = { version = "1.53.3", features = ["rt-multi-thread", "macros"] }
+2 -2
View File
@@ -63,8 +63,8 @@ impl ParsedPlan {
///
/// # Errors
/// `PD-ENG-002` when stdout is empty, which is what pip leaves behind when it is too old for
/// `--report` **or** when the SP-2 encoding crash struck; `PD-ENG-003` when the JSON is present
/// but not the shape we know.
/// `--report` **or** when the SP-2 encoding crash struck; `PD-ENG-999` when the JSON is present
/// but not the shape we know — not `PD-ENG-003`, whose advice is to switch to pip.
pub fn pip_report(stdout: &str, stderr: &str, installed: &[Dist]) -> Result<ParsedPlan> {
// Checked before anything is parsed, because the SP-2 crash does not leave stdout empty — it
// leaves a *truncated* report, written up to the byte that could not be encoded. That is more
+4 -2
View File
@@ -7,8 +7,10 @@
//!
//! Two consequences shape this adapter:
//!
//! - `resolve` parses the plan whether or not uv exited zero, because its failure message is the
//! most useful thing it produces.
//! - `resolve` is decided by uv's exit status first: zero is a plan; a non-zero exit whose text
//! says no solution exists is a report (`impossible`), and anything else — a build failure, an
//! unreachable index — is classified as the failure it is. Parsing the plan regardless of the
//! exit status is how a failed build used to read as "nothing to change" (C3).
//! - Every plan restates the installed set as explicit requirements. Without that, uv upgrades
//! straight past an installed package's constraint and exits 0 — see [`super::plan_requirements`].
//!
+1 -1
View File
@@ -289,7 +289,7 @@ impl Command {
/// Run to completion, capturing output. See [`TreeGuard`] for what "stop" means here.
///
/// # Errors
/// `PD-ENG-001` when the program cannot be spawned, `PD-INT-001` when the watchdog fires.
/// `PD-ENG-001` when the program cannot be spawned, `PD-ENG-004` when the watchdog fires.
pub async fn run(&self) -> Result<Output> {
let started = self.logged_start();
// Spawned rather than `.output()`ed, so the child can be put in a job before it is waited
+2 -2
View File
@@ -260,8 +260,8 @@ pub async fn recheck(
/// and `RuffFindings.fixable` counts only `Safe` for the same reason — the number in the dialog
/// has to be the number the fix delivers.
///
/// **`ruff format` is deliberately not wired.** §4's `--check` toggle is read-only and stays
/// default-off. Formatting a whole project is a far larger blast radius than fixing seventeen lint
/// **`ruff format` is deliberately not wired**, not even as a check (CODE-HEALTH-SPEC §1).
/// Formatting a whole project is a far larger blast radius than fixing seventeen lint
/// findings, and §7's non-goals are contractual per ROADMAP's standing risks.
///
/// # Errors
+5 -3
View File
@@ -37,7 +37,8 @@ pub const TOOL_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(120
/// CODE-HEALTH-SPEC §4: vulture's default confidence floor.
pub const DEFAULT_MIN_CONFIDENCE: u8 = 80;
/// CODE-HEALTH-SPEC §4: directories excluded from every tool, plus user globs from Settings.
/// CODE-HEALTH-SPEC §4: directories excluded from every tool. (Settings has no globs of its
/// own; a project's `exclude` in its own config is respected by ruff as usual.)
pub const DEFAULT_EXCLUDES: &[&str] = &[".venv", "venv", "node_modules", "build", "dist", ".git"];
/// The release-time pin ledger, baked into the binary (CODE-HEALTH-SPEC §2).
@@ -1340,8 +1341,9 @@ mod tests {
/// The whole bootstrap, against real PyPI, into a scratch directory.
///
/// `#[ignore]`d because `cargo test --workspace` must not need a network. CI runs it explicitly
/// (`ci-integration.yml`), and so should anyone touching this module:
/// `#[ignore]`d because `cargo test --workspace` must not need a network. No CI job runs this
/// test — `ci-integration.yml` drives the same bootstrap end to end through `pipdock tools
/// sync` instead — so anyone touching this module should:
/// `cargo test -p pipdock-core -- --ignored the_bootstrap`.
#[tokio::test]
#[ignore = "hits real PyPI; run with --ignored"]
+7 -3
View File
@@ -272,8 +272,10 @@ pub struct RefreshReport {
/// offers to disable verification.
///
/// # Errors
/// `PD-NET-010` when the fetch or ingest fails. The previous index is left in place and stays
/// searchable, because a failed refresh must not cost the user the index they already had.
/// `PD-NET-001`/`PD-NET-002` when PyPI cannot be reached or TLS fails (read from the error's
/// source chain), `PD-NET-010` when it answers with something that is not an index. Either way
/// the previous index is left in place and stays searchable, because a failed refresh must not
/// cost the user the index they already had.
pub async fn refresh(app_data: &std::path::Path, now: jiff::Timestamp) -> Result<RefreshReport> {
let started = std::time::Instant::now();
@@ -517,7 +519,9 @@ fn cached_metadata(
async fn fetch_metadata(name: &PkgName) -> Result<PackageMeta> {
let url = format!("https://pypi.org/pypi/{}/json", name.as_str());
let response = http_client()?
// The shared client: a new one per call meant a new connection pool and TLS handshake for
// every package opened in Search (M37).
let response = shared_client()?
.get(&url)
.send()
.await
+1 -1
View File
@@ -34,11 +34,11 @@ pub mod exec;
// reads them, so they are not compiled into one.
#[cfg(any(test, feature = "fixtures"))]
pub mod fixtures;
// build.rs's legal-documents hash, compiled here only so its tests run with the others.
pub mod flow;
pub mod graph;
pub mod health;
pub mod index;
// build.rs's legal-documents hash, compiled here only so its tests run with the others.
#[cfg(test)]
mod legal_hash;
pub mod logging;
+1 -1
View File
@@ -258,7 +258,7 @@ pub struct ExecutionSummary {
pub counts: Counts,
/// True when the user stopped this run part-way.
///
/// ARCHITECTURE §7 words this as `Skipped(UserCancelled)`, but [`StepStatus`] is a
/// DATA-FLOW §3 used to word this as `Skipped(UserCancelled)`, but [`StepStatus`] is a
/// payload-free enum and giving it one changes the wire shape for every consumer. A flag on
/// the summary also matches what the summary sheet actually needs: "cancelled" is said once
/// at the top, not repeated on forty rows.
+1 -1
View File
@@ -1,7 +1,7 @@
{
"$schema": "../gen/schemas/desktop-schema.json",
"identifier": "default",
"description": "Exactly what the webview calls, and nothing preemptive (docs/SECURITY.md §2); lib.rs pins the set with a test. core:default stood here until 1.4.0: it granted some sixty core commands nothing used and not the one the legal gate's Decline needs, so Decline did nothing in the installed app. core:event:allow-listen/unlisten carry plan-, scan-, health- and audit-progress; core:window:allow-close is Decline. dialog:allow-open is Code Health's project-folder picker and Import requirements; dialog:allow-save is Save report and Export. BOTH ONLY ASK FOR A PATH — no fs permission is granted, so the webview cannot read or write a single file. Save report hands its path to a Rust command that writes the two files, because a general fs:allow-write-text-file would be a write-anywhere primitive in the webview of a tool that already runs subprocesses against the user's interpreters.",
"description": "Exactly what the webview calls, and nothing preemptive (docs/SECURITY.md §4); lib.rs pins the set with a test. core:default stood here until 1.4.0: it granted some sixty core commands nothing used and not the one the legal gate's Decline needs, so Decline did nothing in the installed app. core:event:allow-listen/unlisten carry plan-, scan-, health- and audit-progress; core:window:allow-close is Decline. dialog:allow-open is Code Health's project-folder picker and Import requirements; dialog:allow-save is Save report and Export. BOTH ONLY ASK FOR A PATH — no fs permission is granted, so the webview cannot read or write a single file. Save report hands its path to a Rust command that writes the two files, because a general fs:allow-write-text-file would be a write-anywhere primitive in the webview of a tool that already runs subprocesses against the user's interpreters.",
"windows": ["main"],
"permissions": [
"core:event:allow-listen",
+9 -1
View File
@@ -954,7 +954,15 @@ pub async fn snapshot_diff(
let hash = envs::env_hash(&env.interpreter);
let snap = snapshot::load(&state.app_data, &hash, &id)?;
let current = snapshot::parse_freeze(&engine.freeze(&env).await?);
Ok(snapshot::diff(&current, &snap.entries()))
// What a rollback with this engine would see, as the CLI's `snapshot diff` and the rollback
// itself do. A plain diff here showed pip and setuptools as changes across engines that the
// rollback, rightly, would never touch — the two heads disagreed (G5).
Ok(snapshot::restorable_diff(
&current,
&snap.entries(),
snap.meta.engine,
engine.id(),
))
}
/// What restoring a snapshot would do, parking the flow that would do it (DATA-FLOW §8).
+56 -2
View File
@@ -511,15 +511,22 @@ impl AppState {
})
}
/// Claim the index slot for a load, if one is not already done or running.
/// Claim the index slot for a load, if one has not been tried yet.
///
/// Returns `true` when the caller is now responsible for loading. Idempotent, so calling it on
/// every Search render is harmless — which is what lets the screen ask without coordinating.
///
/// **Only from `Cold`.** A failed load stays failed until a refresh clears it
/// ([`Self::invalidate_index`]) or the app restarts. This used to restart from `Failed` too,
/// which flipped the slot back to `Warming` *before* the search could report why — so on a
/// profile that had never downloaded the index, every answer said "warming", the screen asked
/// again every 150 ms, and the prompt to download the index never appeared. Found by running
/// the installed 1.4.0 build on a fresh profile.
pub fn begin_index_load(&self) -> bool {
let Ok(mut slot) = self.index.lock() else {
return false;
};
if matches!(*slot, IndexSlot::Cold | IndexSlot::Failed(_)) {
if matches!(*slot, IndexSlot::Cold) {
*slot = IndexSlot::Warming;
return true;
}
@@ -586,6 +593,53 @@ mod tests {
Sessions::default()
}
/// An `AppState` over a store in a fresh temporary directory.
fn app_state(tag: &str) -> (AppState, PathBuf) {
let dir = std::env::temp_dir().join(format!("pipdock-state-{tag}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
let store = Store::open(&dir).expect("a store in a temp dir");
let state = AppState {
app_data: dir.clone(),
store: tokio::sync::Mutex::new(store),
index: std::sync::Mutex::new(IndexSlot::Cold),
sessions: Sessions::default(),
health: Sessions::default(),
audit: Sessions::default(),
log: std::sync::Arc::new(LogRing::default()),
};
(state, dir)
}
#[test]
fn a_failed_index_load_says_why_rather_than_warming_forever() {
let (state, dir) = app_state("index");
assert!(state.begin_index_load(), "the first search starts a load");
state.finish_index_load(Err(pipdock_core::PdError::new(
Code::NetIndexRefreshFailed,
"the package index is empty",
)));
// The next search must not restart it: restarting reset the slot to Warming before the
// failure could be read, and the screen showed "warming" for ever on a fresh profile.
assert!(
!state.begin_index_load(),
"a failed load is not retried by a search"
);
assert_eq!(
state.index_failure().as_deref(),
Some("the package index is empty")
);
// A refresh is what clears it.
state.invalidate_index();
assert!(
state.begin_index_load(),
"after a refresh the next search loads again"
);
drop(state);
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn claiming_an_empty_slot_leaves_it_claimed_for_the_caller() {
let s = sessions();
+2 -2
View File
@@ -17,6 +17,6 @@ deptry==0.25.1
vulture==2.16
ruff==0.17.1
# P1 (Security tab, PRD P1-1). Pinned now so spike SP-4 has something concrete to invoke while
# it settles the foreign-environment audit flags.
# The Security tab (PRD P1-1, shipped in 1.2.0). Installed into its own venv, not Code Health's
# (health::AUDIT_TOOLS), so a bump here never re-syncs the other one.
pip-audit==2.10.1
+4 -1
View File
@@ -79,7 +79,10 @@ export function PdDialog({
e.preventDefault()
if (!busy) onCancel()
}}
className="max-w-lg rounded-pd border border-border bg-surface p-6 text-text backdrop:bg-bg/80"
// `m-auto`: Tailwind's preflight sets `margin: 0` on everything, which removes the
// `margin: auto` a modal <dialog> is centred by — so every dialog opened in the window's
// top-left corner. Seen in the installed build; jsdom computes no layout to show it.
className="m-auto max-w-lg rounded-pd border border-border bg-surface p-6 text-text backdrop:bg-bg/80"
>
<h2 className="text-accent">{title}</h2>
<div className="mt-3 text-data">{children}</div>
+1 -1
View File
@@ -101,7 +101,7 @@ describe('pins', () => {
// names the version. Matched by title, not text: a hold is usually at the package's current
// version, so "1.26.4" legitimately appears in both the version cell and the chip.
expect(
within(rowFor('scipy') as HTMLElement).getByTitle(/left out of bulk updates/i),
within(rowFor('scipy') as HTMLElement).getByTitle(/left out of every update/i),
).toHaveTextContent('pinned')
expect(within(rowFor('numpy') as HTMLElement).getByTitle(/^Held at 1\.26\.4/)).toBeInTheDocument()
})
+2 -1
View File
@@ -190,7 +190,8 @@ export function PdPalette({ onClose }: { onClose: () => void }) {
// Backdrop only: clicks inside the panel below stop here first.
if (e.target === ref.current) onClose()
}}
className="mt-24 w-full max-w-xl rounded-pd border border-border bg-surface p-0 text-text backdrop:bg-bg/80"
// `mx-auto`: preflight's `margin: 0` removed the centring; see PdDialog.
className="mx-auto mt-24 w-full max-w-xl rounded-pd border border-border bg-surface p-0 text-text backdrop:bg-bg/80"
>
<div className="p-3">
<input
+3 -3
View File
@@ -40,9 +40,9 @@ export function PdStatusLine() {
<span aria-hidden="true">{'·'}</span>
<span aria-live="polite">{scanning ? t('status.scanning') : t('status.idle')}</span>
{/* §3 draws a log toggle here and it has been plain text since S1 — a control that looks
like one and does nothing. It opens the console drawer, which is the only log surface
that exists until M3's logging subsystem; disabled when there is no run to show. */}
{/* §3 draws a log toggle here and it was plain text from S1 — a control that looked like
one and did nothing. It opens the console drawer for the run in progress, and is disabled
when there is none. The persistent log is a file since 1.4.0 (Settings → Logs). */}
<button
type="button"
onClick={() => {
+8 -5
View File
@@ -11,9 +11,10 @@ import viErrors from './locales/vi/errors.json'
/**
* i18next setup — `docs/I18N.md`.
*
* §1: `en` is the source of truth; missing `vi` keys fall back to English at runtime with a
* console warning, **never** raw key names in the UI. A CI script fails the build when `vi` is
* short of keys, so the fallback is a safety net rather than a strategy.
* §1: `en` is the source of truth; missing `vi` keys fall back to English at runtime — silently,
* since i18next only calls `missingKeyHandler` with `saveMissing` on (Audit backlog U59) — and
* **never** to raw key names in the UI. `i18n.test.ts` fails when `vi` is short of keys, so the
* fallback is a safety net rather than a strategy.
*
* §2: default locale is the OS UI language when it is Vietnamese, else English; switchable in
* Settings and applied live.
@@ -25,7 +26,7 @@ import viErrors from './locales/vi/errors.json'
* i18next's `nsSeparator` is `:` — churn across every screen, in exchange for lazy loading that a
* desktop app with both catalogs already in the bundle cannot use.
*
* The error codes get their own *file* regardless, and that part is worth it: there are 32 of them,
* The error codes get their own *file* regardless, and that part is worth it: there are 35 of them,
* they are the only keys whose names are a contract with Rust rather than with a screen, and
* `i18n.test.ts` checks them against `Code::ALL` itself. Splitting the file keeps that reviewable
* without splitting the namespace. §1 is amended to say so.
@@ -74,7 +75,9 @@ void i18n.use(initReactI18next).init({
// React already escapes; double-escaping mangles Vietnamese diacritics in some browsers.
escapeValue: false,
},
// Surfaces the fallback in development instead of letting untranslated copy pass unnoticed.
// With `saveMissing` false the handler below is never called: i18next reports only the missing
// keys it is asked to save. Kept for when U59 turns it on in development; the parity test in
// `i18n.test.ts` is the guard that actually runs.
saveMissing: false,
missingKeyHandler: (lngs, ns, key) => {
console.warn(`[i18n] missing key ${ns}:${key} for ${lngs.join(',')}`)
+1 -1
View File
@@ -450,7 +450,7 @@ export interface ExecutionSummary {
/**
* True when the user stopped this run part-way.
*
* ARCHITECTURE §7 words this as `Skipped(UserCancelled)`, but [`StepStatus`] is a
* DATA-FLOW §3 used to word this as `Skipped(UserCancelled)`, but [`StepStatus`] is a
* payload-free enum and giving it one changes the wire shape for every consumer. A flag on
* the summary also matches what the summary sheet actually needs: "cancelled" is said once
* at the top, not repeated on forty rows.
+4 -4
View File
@@ -48,7 +48,7 @@
"pipUpgradeNoSnapshot": "No snapshot is taken: restoring one would need the pip being replaced.",
"title": "Environments",
"empty": "no Python environments found",
"emptyHint": "Install Python, or use Browse… to pick an interpreter.",
"emptyHint": "Install Python, or create a virtual environment named .venv, venv, env or .env in this folder.",
"scanning": "Discovering environments…",
"scanPhase": {
"registry": "Reading the Windows registry",
@@ -82,8 +82,8 @@
"badge": {
"update": "UPDATE",
"pinned": "pinned",
"pinnedDetail": "Pinned: left out of bulk updates. You can still update it on its own.",
"heldDetail": "Held at {{version}}: left out of bulk updates, and restated at this version in every plan."
"pinnedDetail": "Pinned: left out of every update, including one that names it. Unpin it to update it.",
"heldDetail": "Held at {{version}}: kept at this version in every plan, including one that names it."
},
"actions": {
"pin": "Pin this package",
@@ -458,7 +458,7 @@
"docsHash": "Legal documents",
"docsHashDetail": "Your acceptance is recorded against this value. Editing any of the documents changes it, and the acceptance screen appears once more on the next launch.",
"aiTitle": "How this was built",
"aiBody": "PipDock was written with substantial help from an AI coding assistant — Claude Opus 5, made by Anthropic — under human review. It wrote source code, tests and translations; every change was read and merged by the maintainer, and the built application was driven by hand before release. Copyright and the GPL-3.0-only licence are unchanged.",
"aiBody": "PipDock was written with substantial help from an AI coding assistant — Claude Opus 5, and from 1.4.0 Claude Opus 5.5, made by Anthropic — under human review. It wrote source code, tests and translations. The maintainer decides what ships: through 1.3.0 they read and merged every change themselves, and 1.4.0 was released by the assistant on their written instruction, once its checks had passed. Copyright and the GPL-3.0-only licence are unchanged.",
"aiRead": "Read the full disclosure",
"openRepo": "Open the repository",
"reopen": "Show the documents again",
+4 -4
View File
@@ -47,7 +47,7 @@
"pipUpgradeNoSnapshot": "Không tạo bản chụp: khôi phục nó sẽ cần chính pip đang được thay thế.",
"title": "Môi trường",
"empty": "không tìm thấy môi trường Python nào",
"emptyHint": "Hãy cài Python, hoặc dùng Duyệt… để chọn một trình thông dịch.",
"emptyHint": "Hãy cài Python, hoặc tạo một môi trường ảo tên .venv, venv, env hoặc .env trong thư mục này.",
"scanning": "Đang tìm môi trường…",
"scanPhase": {
"registry": "Đang đọc registry của Windows",
@@ -81,8 +81,8 @@
"badge": {
"update": "UPDATE",
"pinned": "đã ghim",
"pinnedDetail": "Đã ghim: không nằm trong các lần cập nhật hàng loạt. Bạn vẫn có thể cập nhật riêng gói này.",
"heldDetail": "Giữ ở {{version}}: không nằm trong cập nhật hàng loạt, và luôn được giữ ở phiên bản này trong mọi kế hoạch."
"pinnedDetail": "Đã ghim: không nằm trong bất kỳ lần cập nhật nào, kể cả khi được chọn đích danh. Bỏ ghim để cập nhật.",
"heldDetail": "Giữ ở {{version}}: luôn giữ phiên bản này trong mọi kế hoạch, kể cả khi được chọn đích danh."
},
"actions": {
"pin": "Ghim gói này",
@@ -414,7 +414,7 @@
"docsHash": "Tài liệu pháp lý",
"docsHashDetail": "Việc bạn chấp nhận được ghi lại kèm giá trị này. Sửa bất kỳ tài liệu nào cũng làm nó đổi, và màn hình chấp nhận sẽ hiện lại một lần ở lần mở tiếp theo.",
"aiTitle": "Ứng dụng này được làm ra thế nào",
"aiBody": "PipDock được viết với sự hỗ trợ đáng kể của một trợ lý lập trình AI — Claude Opus 5, do Anthropic phát triển — dưới sự rà soát của con người. Nó viết mã nguồn, kiểm thử và bản dịch; mọi thay đổi đều do người bảo trì đọc và hợp nhất, và bản dựng hoàn chỉnh được chạy tay trước khi phát hành. Bản quyền và giấy phép GPL-3.0-only không thay đổi.",
"aiBody": "PipDock được viết với sự hỗ trợ đáng kể của một trợ lý lập trình AI — Claude Opus 5, và từ 1.4.0 là Claude Opus 5.5, do Anthropic phát triển — dưới sự rà soát của con người. Nó viết mã nguồn, kiểm thử và bản dịch. Người bảo trì quyết định những gì được phát hành: tới 1.3.0, họ tự đọc và hợp nhất mọi thay đổi; bản 1.4.0 do trợ lý phát hành theo chỉ thị bằng văn bản của họ, sau khi các bước kiểm tra đã đạt. Bản quyền và giấy phép GPL-3.0-only không thay đổi.",
"aiRead": "Đọc bản công bố đầy đủ",
"openRepo": "Mở kho mã nguồn",
"reopen": "Xem lại các tài liệu",
+4 -5
View File
@@ -6,11 +6,10 @@
* inventory, so it is built from the primitives; the 🔒 chip is `PdPinChip`, shared with the table
* rather than re-derived, or the two would eventually disagree about which mode is which.
*
* **Exclude only.** The screen shows a `Hold` pin faithfully if one exists — the CLI could write
* one in principle — but does not offer to create one, because `pins::hold_requirements` is dead
* code in the core and `engine::plan_requirements` restates each package at its *installed*
* version. A hold at any other version is a promise nothing keeps, and offering it here would be
* the interface lying about what the engine does.
* **Exclude only.** The screen shows a `Hold` pin faithfully if one exists — the CLI can write
* one — but does not offer to create one. Holds are honoured since 1.4.0 (`GuardAdjust.pins`
* restates a held package at its held version), but nothing here asks for the version to hold
* at, and a hold the user cannot see the version of is worse than none.
*
* The reason commits on blur rather than on every keystroke: it is a `pin_add` upsert per commit,
* and one round trip per character typed is a lot of SQLite for a text field.
+4 -1
View File
@@ -68,7 +68,10 @@ interface SettingsState {
* the language the OS happened to resolve to (U3).
*/
localeChoice: Locale | null
/** Configured engine. First run pre-selects uv when it is on PATH (ARCHITECTURE §3). */
/**
* Configured engine; pip until the user picks. ARCHITECTURE §3 describes a first run that
* pre-selects uv when it is on PATH — that is not built (Audit backlog X19).
*/
engine: EngineId
/**
* PEP 668 override. Off by default and deliberately hard to turn on — SECURITY §3 requires