167 lines
7.2 KiB
Markdown
167 lines
7.2 KiB
Markdown
# PR-11 Pack Wizard Shell and Packer Contract Consumption
|
|
|
|
Domain owner: `docs/studio`
|
|
Cross-domain impact: `docs/packer`
|
|
|
|
## Briefing
|
|
|
|
The `Pack` action in the `Assets` workspace is now closed as a Studio wizard over packer-owned operations.
|
|
|
|
The Studio decision already fixes the operational boundary:
|
|
|
|
- Studio is the shell;
|
|
- packer owns summary, validation, pack execution, progress, and result semantics;
|
|
- the wizard has four phases:
|
|
`Summary`, `Validation`, `Packing`, `Result`;
|
|
- validation runs only on the current `registered + included in build` set;
|
|
- blocking diagnostics stop the flow before execution;
|
|
- the first wave is non-cancelable.
|
|
|
|
The packer-side API PR also defines the contracts that Studio must consume:
|
|
|
|
- pack summary
|
|
- pack validation
|
|
- pack execution
|
|
|
|
This PR implements the Studio side of that contract.
|
|
|
|
References:
|
|
|
|
- [`../decisions/Pack Wizard in Assets Workspace Decision.md`](../decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
|
|
- [`../../packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](../../packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md)
|
|
|
|
## Objective
|
|
|
|
Deliver the `Pack` wizard shell in the `Assets` workspace and bind it to the public packer contracts for summary, validation, progress, and result.
|
|
|
|
## Dependencies
|
|
|
|
- [`../decisions/Pack Wizard in Assets Workspace Decision.md`](../decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md)
|
|
- [`./PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md)
|
|
- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md)
|
|
- [`./PR-07d-asset-mutation-and-structural-sync-orchestration.md`](./PR-07d-asset-mutation-and-structural-sync-orchestration.md)
|
|
- cross-domain reference:
|
|
[`../../packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](../../packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md)
|
|
|
|
## Scope
|
|
|
|
- add a real `Pack` action entry point in the `Assets` workspace action bar
|
|
- open a dedicated modal wizard from that button
|
|
- implement the wizard shell with four explicit phases:
|
|
- `Summary`
|
|
- `Validation`
|
|
- `Packing`
|
|
- `Result`
|
|
- consume packer summary API for the first phase
|
|
- consume packer validation API for the second phase
|
|
- consume packer pack execution API for the third phase
|
|
- bind packer operation progress to the wizard progress UI
|
|
- render result data from the final pack execution response
|
|
- show blocking diagnostics by default in `Validation`
|
|
- allow developer drill-down on per-asset validation entries
|
|
- keep `Packing` non-editable and non-cancelable in the first wave
|
|
- keep companion artifacts in secondary drill-down in `Result`
|
|
- allow a `dumb` future-facing export/copy button without real behavior if the shell needs a visible reminder
|
|
|
|
## Non-Goals
|
|
|
|
- no local Studio recomputation of build-set semantics
|
|
- no local Studio validation engine for pack gating
|
|
- no fake timer-based progress
|
|
- no cancellation in the first wave
|
|
- no direct implementation of packer semantics inside Studio
|
|
- no asset-details-local `Pack`; this remains a workspace-level flow
|
|
|
|
## Execution Method
|
|
|
|
1. Wire the `Pack` action in the workspace action bar to open the new wizard.
|
|
|
|
2. Build a dedicated wizard shell control for the `Assets` workspace.
|
|
The shell should own:
|
|
- phase navigation
|
|
- modal presentation
|
|
- loading states
|
|
- error surfaces
|
|
- binding to packer responses and progress events
|
|
|
|
3. Implement the `Summary` phase as packer-backed preflight.
|
|
Rules:
|
|
- request pack summary on open;
|
|
- do not reconstruct counts from navigator rows;
|
|
- show the canonical artifact name `assets.pa`;
|
|
- show the build-set counts returned by packer.
|
|
|
|
4. Implement the `Validation` phase as packer-backed gate inspection.
|
|
Rules:
|
|
- call the validation API explicitly;
|
|
- render aggregate counts and per-asset entries;
|
|
- show blocking diagnostics by default;
|
|
- allow drill-down to inspect more context on each asset;
|
|
- block advance into `Packing` when validation fails.
|
|
|
|
5. Implement the `Packing` phase as an operational waiting surface.
|
|
Rules:
|
|
- call pack execution explicitly only after successful validation;
|
|
- show progress bar and current-step text from packer-driven state;
|
|
- keep the modal non-editable;
|
|
- do not expose real cancel behavior in the first wave.
|
|
|
|
6. Implement the `Result` phase as packer-result rendering.
|
|
Rules:
|
|
- show final status;
|
|
- show total assets packed;
|
|
- show elapsed time when available from the contract;
|
|
- keep `assets.pa` visible in the main summary;
|
|
- move companion artifacts into secondary drill-down.
|
|
|
|
7. Integrate the operation with Studio progress and activity surfaces where appropriate.
|
|
The wizard-local progress surface is primary during execution, but existing global operational surfaces should remain coherent with the same operation.
|
|
|
|
8. Keep the implementation boundary strict.
|
|
Studio may orchestrate calls and render states, but it must not decide:
|
|
- what the pack set is;
|
|
- what counts as blocking;
|
|
- how `asset_table` ordering is determined;
|
|
- or what artifacts were emitted beyond what packer reports.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- clicking `Pack` in the `Assets` workspace opens a dedicated modal wizard
|
|
- the wizard has explicit `Summary`, `Validation`, `Packing`, and `Result` phases
|
|
- `Summary` is populated from packer summary data rather than local UI reconstruction
|
|
- `Validation` is populated from packer validation data
|
|
- validation failure blocks transition into `Packing`
|
|
- blocking diagnostics are visible by default in the validation phase
|
|
- per-asset drill-down exists for developer inspection
|
|
- `Packing` shows packer-driven progress and remains non-editable
|
|
- the first wave does not expose real cancellation
|
|
- `Result` renders final packer result data and keeps companion artifacts secondary
|
|
- the Studio implementation remains a shell over packer contracts rather than a second semantic engine
|
|
|
|
## Validation
|
|
|
|
- unit tests for wizard phase state transitions
|
|
- unit tests for mapping summary response into the `Summary` phase
|
|
- unit tests for validation gating and blocked advance into `Packing`
|
|
- unit tests for per-asset validation drill-down state
|
|
- unit tests for progress binding from packer operation state into the wizard progress UI
|
|
- unit tests for result rendering from pack execution response
|
|
- smoke test for:
|
|
- open wizard
|
|
- load summary
|
|
- run validation
|
|
- stop on blockers
|
|
- advance on valid state
|
|
- show packing progress
|
|
- render final result
|
|
|
|
## Affected Artifacts
|
|
|
|
- `docs/studio/specs/4. Assets Workspace Specification.md` if the wizard shell behavior needs more explicit normative wording
|
|
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
|
|
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/**`
|
|
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/wizards/**`
|
|
- `prometeu-studio/src/main/java/p/studio/events/**` if new UI-local orchestration events are needed
|
|
- `prometeu-studio/src/main/resources/i18n/messages.properties`
|
|
- `prometeu-studio/src/test/java/p/studio/workspaces/assets/**`
|