feat(core): FlowStep and Intent cross the IPC boundary
The GUI's two decision points are IPC round trips with a render in between — that is why `core::flow` is resumable rather than callback-driven, and it is the whole reason the preview can be drawn at all. But the types those round trips carry were not serializable: `FlowStep` had no `Serialize` and `Intent` had neither, so the flow could be driven from Rust and from nowhere else. Both are now tagged enums with camelCase fields, generating as discriminated unions the frontend can switch on directly. Tagged internally rather than externally so a consumer can look at `step` without unwrapping first. `roundsRemaining` comes out with them, and it closes a gap worth naming: `MAX_CONFLICT_ROUNDS` has existed in core since M1 with nothing surfacing it, so a user could hit the cap with no warning that it was approaching. The preview can now say so before the last round. `Decision`, `Strategy` and `ResolutionReport` already had what they needed — no change. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
82ffab23f3
commit
e57870b3d9
7 files changed
+431
-4
No files matched your search
@@ -44,6 +44,8 @@ const SCHEMA_TYPES: &[&str] = &[
|
||||
"Hit",
|
||||
"PackageMeta",
|
||||
"ProgressEvent",
|
||||
"FlowStep",
|
||||
"Intent",
|
||||
"Code",
|
||||
];
|
||||
|
||||
|
||||
@@ -0,0 +1,299 @@
|
||||
---
|
||||
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"
|
||||
},
|
||||
"NothingReason": {
|
||||
"description": "Why a flow ended before there was anything to confirm.",
|
||||
"oneOf": [
|
||||
{
|
||||
"const": "nothing-to-do",
|
||||
"description": "The request was empty once pins and `--except` were applied.",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "everything-skipped",
|
||||
"description": "Every candidate was skipped while resolving conflicts, so no plan remains.",
|
||||
"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"
|
||||
},
|
||||
"ResolutionReport": {
|
||||
"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"
|
||||
},
|
||||
"heldBack": {
|
||||
"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"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"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": "What the flow needs next.\n\nCrosses IPC, so the GUI's two decision points are a round trip apart (see the module docs).\nTagged on `step` rather than externally, because the frontend switches on it and a bare\n`{ needsDecisions: { … } }` would make every consumer unwrap before it can look.",
|
||||
"oneOf": [
|
||||
{
|
||||
"description": "Conflicts need a per-package choice. Feed the answers to [`UpdateFlow::decide`].",
|
||||
"properties": {
|
||||
"report": {
|
||||
"$ref": "#/$defs/ResolutionReport",
|
||||
"description": "The preview as it stands."
|
||||
},
|
||||
"round": {
|
||||
"description": "How many decision rounds have been applied.",
|
||||
"format": "uint8",
|
||||
"maximum": 255,
|
||||
"minimum": 0,
|
||||
"type": "integer"
|
||||
},
|
||||
"roundsRemaining": {
|
||||
"description": "Rounds still available before the cap (DATA-FLOW §3).\n\nSurfaced because `MAX_CONFLICT_ROUNDS` was invisible: the cap existed in core and\nnothing told the user it was approaching, so they would hit the wall unwarned.",
|
||||
"format": "uint8",
|
||||
"maximum": 255,
|
||||
"minimum": 0,
|
||||
"type": "integer"
|
||||
},
|
||||
"step": {
|
||||
"const": "needsDecisions",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"step",
|
||||
"report",
|
||||
"round",
|
||||
"roundsRemaining"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
{
|
||||
"description": "The preview is ready to confirm.",
|
||||
"properties": {
|
||||
"report": {
|
||||
"$ref": "#/$defs/ResolutionReport",
|
||||
"description": "The preview as it stands."
|
||||
},
|
||||
"step": {
|
||||
"const": "needsConfirm",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"step",
|
||||
"report"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
{
|
||||
"description": "The conflict-round cap is reached; the remaining conflicts cannot be re-decided.\n\nDistinct from [`Self::NeedsConfirm`] so the GUI can say so, but the plan is still\nconfirmable — which is what the CLI has always done at this point.",
|
||||
"properties": {
|
||||
"report": {
|
||||
"$ref": "#/$defs/ResolutionReport",
|
||||
"description": "The preview as it stands."
|
||||
},
|
||||
"step": {
|
||||
"const": "roundsExhausted",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"step",
|
||||
"report"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
{
|
||||
"description": "There is nothing to do.",
|
||||
"properties": {
|
||||
"reason": {
|
||||
"$ref": "#/$defs/NothingReason",
|
||||
"description": "Which of the two empty cases this is."
|
||||
},
|
||||
"step": {
|
||||
"const": "nothing",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"step",
|
||||
"reason"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
],
|
||||
"title": "FlowStep"
|
||||
}
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
source: crates/pipdock-cli/tests/golden.rs
|
||||
expression: out
|
||||
---
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"description": "What the user asked for, before it becomes a [`PlanRequest`].\n\nNames arrive as strings and are parsed here rather than by the caller, so both heads get the\nsame `PD-PKG-002` on a malformed name and SECURITY §2's \"validated before it reaches argv\"\nholds for the GUI as well as the CLI.",
|
||||
"oneOf": [
|
||||
{
|
||||
"description": "`pipdock update`",
|
||||
"properties": {
|
||||
"all": {
|
||||
"description": "Every outdated package.",
|
||||
"type": "boolean"
|
||||
},
|
||||
"except": {
|
||||
"default": [],
|
||||
"description": "Ad-hoc exclusions on top of pins.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"forceLatest": {
|
||||
"default": false,
|
||||
"description": "`--strategy latest`.",
|
||||
"type": "boolean"
|
||||
},
|
||||
"intent": {
|
||||
"const": "update",
|
||||
"type": "string"
|
||||
},
|
||||
"pkgs": {
|
||||
"default": [],
|
||||
"description": "Specific packages.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"intent",
|
||||
"all"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
{
|
||||
"description": "`pipdock install`",
|
||||
"properties": {
|
||||
"intent": {
|
||||
"const": "install",
|
||||
"type": "string"
|
||||
},
|
||||
"specs": {
|
||||
"description": "`name` or `name==version`.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"intent",
|
||||
"specs"
|
||||
],
|
||||
"type": "object"
|
||||
}
|
||||
],
|
||||
"title": "Intent"
|
||||
}
|
||||
@@ -2,4 +2,4 @@
|
||||
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, ProgressEvent, Code
|
||||
error[PD-PKG-002]: unknown type "NoSuchType"; known types: Dist, OutdatedDist, PyEnv, CheckReport, StepResult, PlanRequest, ResolutionReport, ExecutionSummary, Pin, GuardReport, Diff, SnapshotMeta, Hit, PackageMeta, ProgressEvent, FlowStep, Intent, Code
|
||||
@@ -51,17 +51,25 @@ use tokio_util::sync::CancellationToken;
|
||||
/// Names arrive as strings and are parsed here rather than by the caller, so both heads get the
|
||||
/// same `PD-PKG-002` on a malformed name and SECURITY §2's "validated before it reaches argv"
|
||||
/// holds for the GUI as well as the CLI.
|
||||
#[derive(Debug, Clone)]
|
||||
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
|
||||
#[serde(
|
||||
tag = "intent",
|
||||
rename_all = "camelCase",
|
||||
rename_all_fields = "camelCase"
|
||||
)]
|
||||
pub enum Intent {
|
||||
/// `pipdock update`
|
||||
Update {
|
||||
/// Every outdated package.
|
||||
all: bool,
|
||||
/// Specific packages.
|
||||
#[serde(default)]
|
||||
pkgs: Vec<String>,
|
||||
/// Ad-hoc exclusions on top of pins.
|
||||
#[serde(default)]
|
||||
except: Vec<String>,
|
||||
/// `--strategy latest`.
|
||||
#[serde(default)]
|
||||
force_latest: bool,
|
||||
},
|
||||
/// `pipdock install`
|
||||
@@ -72,7 +80,9 @@ pub enum Intent {
|
||||
}
|
||||
|
||||
/// Why a flow ended before there was anything to confirm.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
|
||||
#[derive(
|
||||
Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize, schemars::JsonSchema,
|
||||
)]
|
||||
#[serde(rename_all = "kebab-case")]
|
||||
pub enum NothingReason {
|
||||
/// The request was empty once pins and `--except` were applied.
|
||||
@@ -82,7 +92,16 @@ pub enum NothingReason {
|
||||
}
|
||||
|
||||
/// What the flow needs next.
|
||||
#[derive(Debug)]
|
||||
///
|
||||
/// Crosses IPC, so the GUI's two decision points are a round trip apart (see the module docs).
|
||||
/// Tagged on `step` rather than externally, because the frontend switches on it and a bare
|
||||
/// `{ needsDecisions: { … } }` would make every consumer unwrap before it can look.
|
||||
#[derive(Debug, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
|
||||
#[serde(
|
||||
tag = "step",
|
||||
rename_all = "camelCase",
|
||||
rename_all_fields = "camelCase"
|
||||
)]
|
||||
pub enum FlowStep {
|
||||
/// Conflicts need a per-package choice. Feed the answers to [`UpdateFlow::decide`].
|
||||
NeedsDecisions {
|
||||
@@ -91,6 +110,9 @@ pub enum FlowStep {
|
||||
/// How many decision rounds have been applied.
|
||||
round: u8,
|
||||
/// Rounds still available before the cap (DATA-FLOW §3).
|
||||
///
|
||||
/// Surfaced because `MAX_CONFLICT_ROUNDS` was invisible: the cap existed in core and
|
||||
/// nothing told the user it was approaching, so they would hit the wall unwarned.
|
||||
rounds_remaining: u8,
|
||||
},
|
||||
/// The preview is ready to confirm.
|
||||
|
||||
@@ -273,6 +273,8 @@ pub fn json_schema(type_name: &str) -> Result<serde_json::Value> {
|
||||
"Hit" => crate::index::Hit,
|
||||
"PackageMeta" => crate::index::PackageMeta,
|
||||
"ProgressEvent" => crate::engine::ProgressEvent,
|
||||
"FlowStep" => crate::flow::FlowStep,
|
||||
"Intent" => crate::flow::Intent,
|
||||
"Code" => crate::errors::Code,
|
||||
}
|
||||
}
|
||||
@@ -294,6 +296,8 @@ pub const SCHEMA_TYPES: &[&str] = &[
|
||||
"Hit",
|
||||
"PackageMeta",
|
||||
"ProgressEvent",
|
||||
"FlowStep",
|
||||
"Intent",
|
||||
"Code",
|
||||
];
|
||||
|
||||
|
||||
@@ -191,6 +191,19 @@ export interface ExecutionSummary {
|
||||
results?: StepResult[];
|
||||
}
|
||||
|
||||
/**
|
||||
* What the flow needs next.
|
||||
*
|
||||
* Crosses IPC, so the GUI's two decision points are a round trip apart (see the module docs).
|
||||
* Tagged on `step` rather than externally, because the frontend switches on it and a bare
|
||||
* `{ needsDecisions: { … } }` would make every consumer unwrap before it can look.
|
||||
*/
|
||||
export type FlowStep =
|
||||
| { report: ResolutionReport; round: number; roundsRemaining: number; step: 'needsDecisions' }
|
||||
| { report: ResolutionReport; step: 'needsConfirm' }
|
||||
| { report: ResolutionReport; step: 'roundsExhausted' }
|
||||
| { reason: NothingReason; step: 'nothing' };
|
||||
|
||||
/**
|
||||
* What the uninstall guard found.
|
||||
*
|
||||
@@ -241,12 +254,28 @@ export interface ImpossibleDetail {
|
||||
packages?: PkgName[];
|
||||
}
|
||||
|
||||
/**
|
||||
* What the user asked for, before it becomes a [`PlanRequest`].
|
||||
*
|
||||
* Names arrive as strings and are parsed here rather than by the caller, so both heads get the
|
||||
* same `PD-PKG-002` on a malformed name and SECURITY §2's "validated before it reaches argv"
|
||||
* holds for the GUI as well as the CLI.
|
||||
*/
|
||||
export type Intent =
|
||||
| { all: boolean; except?: string[]; forceLatest?: boolean; intent: 'update'; pkgs?: string[] }
|
||||
| { intent: 'install'; specs: string[] };
|
||||
|
||||
/** How a hit matched, in ranking order. */
|
||||
export type MatchKind =
|
||||
| 'exact'
|
||||
| 'prefix'
|
||||
| 'fuzzy';
|
||||
|
||||
/** Why a flow ended before there was anything to confirm. */
|
||||
export type NothingReason =
|
||||
| 'nothing-to-do'
|
||||
| 'everything-skipped';
|
||||
|
||||
/** An installed distribution with a newer release available. */
|
||||
export interface OutdatedDist {
|
||||
/** Currently installed version. */
|
||||
|
||||
Reference in new issue
Block a user