57 lines
3.2 KiB
Markdown
57 lines
3.2 KiB
Markdown
---
|
|
id: LSN-0022
|
|
ticket: studio-play-stop-cartridge-flow
|
|
title: Studio Play/Stop and Debugger Workspace Integration
|
|
status: done
|
|
created: 2026-04-07
|
|
tags: [studio, play-stop, debugger, runtime, shipper]
|
|
---
|
|
|
|
## Summary
|
|
|
|
This lesson covers the implementation of the first wave of the `Play/Stop` flow in Studio and its integration with a native `DebugWorkspace`.
|
|
|
|
The feature enables developers to:
|
|
- Press `Play` to build, pack, and run the current project in the configured runtime.
|
|
- Automatically navigate to a `DebugWorkspace` that shows merged preparation and runtime logs.
|
|
- Press `Stop` to kill the active runtime process.
|
|
|
|
## Key Decisions
|
|
|
|
Based on `DEC-0020`, `DEC-0021`, and `DEC-0022`:
|
|
|
|
1. **Preparation Pipeline**: The `Play` flow orchestrates existing domain operations: `build` -> `validate pack` -> `pack` -> `manifest generation`. All artifacts are kept in `build/`, avoiding a redundant `cartridge/` directory for this wave.
|
|
2. **Runtime Command**: The runtime is executed externally as `"<runtimePath>" run build` with the project root as its working directory.
|
|
3. **Process Ownership**: Studio owns exactly one active runtime process handle per project shell.
|
|
4. **Merged Logs**: Preparation logs (build, pack validation, pack) and runtime logs (stdout/stderr) are merged into a single execution-session stream.
|
|
5. **Native Debugger Workspace**: A native `DebugWorkspace` hosts the execution session and acts as the primary log sink. It is not an external launcher but a real Studio workspace.
|
|
6. **Shared Session State**: The execution state (`idle`, `preparing`, `connecting`, `running`, etc.) lives outside the visual workspace lifecycle in a shared `StudioExecutionSessionService`.
|
|
|
|
## Implementation Details
|
|
|
|
### `StudioPlayStopCoordinator`
|
|
The main orchestrator for the `Play` and `Stop` actions. It:
|
|
- Manages the `preparing` -> `connecting` -> `running` state machine.
|
|
- Invokes the `StudioShipperService` for preparation.
|
|
- Spawns the external runtime process using `StudioExternalRuntimeProcessLauncher`.
|
|
- Merges log streams from both preparation and runtime into the `StudioExecutionSessionService`.
|
|
|
|
### `DebugWorkspace`
|
|
A Studio `Workspace` implementation that reflects the `StudioExecutionSnapshot`. It uses `DebugWorkspaceProjection` to transform the session logs into a display-ready format.
|
|
|
|
### `StudioShipperService`
|
|
Aggregates the domain-specific tasks (compiler build, packer pack) and generates the mandatory `manifest.json` in the `build/` directory.
|
|
|
|
## Common Pitfalls & Anti-Patterns
|
|
|
|
- **Redundant Checks**: Do not add manual `manifest.json` existence checks before spawning. The success of the preparation pipeline already guarantees its presence according to the contract.
|
|
- **State Duplication**: Avoid tracking execution state in both the shell and the workspace. The shared `StudioExecutionSessionService` is the single source of truth.
|
|
- **Technical Linkage**: Do not hard-link the Studio codebase with the legacy `../debugger` repository. Selective migration of protocol/session logic is preferred.
|
|
|
|
## References
|
|
|
|
- `DEC-0020`: Build and pack preparation.
|
|
- `DEC-0021`: External runtime execution.
|
|
- `DEC-0022`: Native `DebugWorkspace` integration.
|
|
- `PLN-0045`: End-to-end execution flow.
|