109 lines
5.1 KiB
Markdown
109 lines
5.1 KiB
Markdown
---
|
|
id: PLN-0045
|
|
ticket: studio-play-stop-cartridge-flow
|
|
title: Ordered Plan 5 - End-to-end Play/Stop execution flow through shipper and DebugWorkspace
|
|
status: review
|
|
created: 2026-04-06
|
|
completed:
|
|
tags: [studio, play-stop, runtime, debugger, shipper, shell]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Wire the full first-wave `Play/Stop` flow end-to-end through shipper preparation, shared execution session state, native debugger destination, external runtime execution, and direct-stop behavior.
|
|
|
|
## Background
|
|
|
|
`DEC-0020`, `DEC-0021`, and `DEC-0022` together now define the intended first-wave behavior. This plan is intentionally last because it integrates the service, session, workspace, and handshake pieces established in the earlier plans.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- `Play` navigation to the debugger destination at flow start.
|
|
- Invocation of shipper preparation.
|
|
- Propagation of preparation failure into the shared session and debugger destination.
|
|
- External runtime spawn `"<runtimePath>" run build` in project root.
|
|
- Runtime output publication into shared session and debugger destination.
|
|
- Direct runtime kill on `Stop`.
|
|
|
|
### Excluded
|
|
- Preparation cancellation.
|
|
- Drift/freshness reuse.
|
|
- `debug` command path.
|
|
- Profiler behavior.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Wire `Play` into the shared execution destination
|
|
|
|
**What:** Make pressing `Play` move the user into the debugger destination immediately.
|
|
**How:** Navigate to `DebugWorkspace` at the beginning of the flow, before runtime spawn, so preparation failures also appear there.
|
|
**File(s):** shell/play controls, workspace selection/navigation logic, `MainView` or equivalent shell coordinator code.
|
|
|
|
### Step 2 - Invoke shipper preparation and reflect preparation state
|
|
|
|
**What:** Start the shipper service and reflect `preparing` / `prepare_failed`.
|
|
**How:** Transition the shared execution session into `preparing`, consume shipper aggregated preparation output, and stop on first preparation failure.
|
|
**File(s):** play orchestration layer, shared session service adapters, shell controls.
|
|
|
|
### Step 3 - Spawn the external runtime process
|
|
|
|
**What:** Execute the exact current-wave runtime command.
|
|
**How:** Use `ProjectLocalStudioSetup.prometeuRuntimePath` and spawn `"<runtimePath>" run build` with `cwd = project root`. Transition through `connecting`, then `running`, or `runtime_failed` on failure.
|
|
**File(s):** runtime orchestration service, shell controls, process-management code.
|
|
|
|
### Step 4 - Wire `Stop` semantics
|
|
|
|
**What:** Kill the active runtime process directly.
|
|
**How:** Keep one active process handle. Ignore repeated `Play` while active. During `preparing`, `Stop` remains a no-op because cancellation is out of scope.
|
|
**File(s):** play/stop controls, runtime orchestration service, shared session service.
|
|
|
|
### Step 5 - Close the end-to-end loop
|
|
|
|
**What:** Ensure all logs and state transitions reach the debugger destination consistently.
|
|
**How:** Route shipper preparation output plus runtime output into the shared session/log sink. Keep the Activity Feed summary-only.
|
|
**File(s):** orchestration layer, shared session adapters, workspace bindings.
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- Verify `Play` transitions the session to `preparing` before runtime spawn.
|
|
- Verify repeated `Play` is ignored while runtime is active.
|
|
- Verify `Stop` kills the active runtime process and does nothing during `preparing`.
|
|
- Verify spawn failures become runtime preflight failures.
|
|
|
|
### Integration Tests
|
|
- End-to-end success path: `Play` opens debugger destination, prepares successfully, spawns runtime, and exposes logs/state.
|
|
- Build failure path: debugger destination opens and shows preparation failure without runtime spawn.
|
|
- Pack-validation failure path: debugger destination opens and shows preparation failure without runtime spawn.
|
|
- Runtime spawn failure path: debugger destination opens and shows runtime failure after successful preparation.
|
|
|
|
### Manual Verification
|
|
- Press `Play` in Studio and confirm the shell navigates to `Debug`.
|
|
- Confirm preparation logs appear before runtime output.
|
|
- Confirm `Stop` kills a running runtime process.
|
|
- Confirm repeated `Play` while running is ignored.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `Play` opens the debugger destination immediately.
|
|
- [ ] The flow executes shipper preparation before runtime spawn.
|
|
- [ ] Preparation failures remain visible in the debugger destination.
|
|
- [ ] Runtime spawn uses the exact command and working-directory contract from `DEC-0021`.
|
|
- [ ] `Stop` kills only the active runtime process and does not cancel preparation.
|
|
- [ ] The debugger destination shows merged preparation and runtime logs end-to-end.
|
|
|
|
## Dependencies
|
|
|
|
- Accepted `DEC-0020`, `DEC-0021`, and `DEC-0022`.
|
|
- `PLN-0041` shipper preparation foundation.
|
|
- `PLN-0042` shared execution session and log contracts.
|
|
- `PLN-0043` first-wave `DebugWorkspace` surface.
|
|
- `PLN-0044` runtime handshake selective integration.
|
|
|
|
## Risks
|
|
|
|
- End-to-end orchestration may reintroduce ownership confusion if shell, shipper, and debugger boundaries are not kept strict.
|
|
- UI timing issues may surface when navigating to the debugger before preparation output begins.
|
|
- Process-lifecycle bugs can leave the shell believing a runtime is still active after failure.
|