Files
prometeu-studio/docs/development.md
T
bquarkz 2d8f6436e4
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
feat(studio): refine Play workspace and project preferences (WRK-001D)
2026-11-22 15:45:09 +00:00

279 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Studio Development Guide
Run commands from the Studio repository root unless stated otherwise.
This guide covers installation, native runtime qualification, external tooling
and opt-in integration checks. See the [project README](../README.md) for the
application overview and basic build commands.
## Native Runtime Installation and Qualification
Build the native umbrella distribution with `../runtime/scripts/local-dist.sh`.
It packages `prometeu`, `prometeu-runtime` (desktop/Studio Play) and
`prometeu-headless` (deterministic automation). Select the extracted
`../runtime/dist-staging/stable/prometeu-cli-<target>` directory in Studio.
An unchanged dispatcher can belong to several releases: Studio selects a profile
only when all three executable hashes match the same qualified bundle.
After changing a native binary, qualify the actual installation before building
or launching Studio with its updated catalog:
```sh
make -C ../tooling venv
../tooling/.venv/bin/python ../tooling/scripts/qualify.py \
--studio . \
--runtime ../runtime/dist-staging/stable/prometeu-cli-aarch64-apple-darwin
```
This command executes the native glyph/scene 16/17 boundary test afresh, verifies
the evidence and executable identities, then publishes an exact capacity profile
under `prometeu-app/src/main/resources/asset-capacity`. Review/include those
resources when distributing Studio. It neither builds a replacement runtime nor
relaxes the execution guard. A failed qualification publishes no catalog entry.
The native build stays independent of the JVM; qualification is an explicit
consumer verification step, separate from pressing Play.
## Installation and IntelliJ Development
Build and stage the complete distribution, including its Java runtime:
```bash
./gradlew :prometeu-app:stageStudioInstallation
```
The macOS default is `~/Library/Application Support/Prometeu/Studio/current`.
Staging validates a new version before atomically changing `current`, retaining
older versions for rollback and running processes. Native client registration
uses absolute paths and argument arrays, independent of shell PATH:
```text
command: <installation>/current/runtime/bin/java
args: ["-cp", "<installation>/current/lib/*", "p.studio.app.StudioLauncher", "mcp", "--project", "<absolute-project-root>"]
```
For development, use an isolated installation:
```bash
./gradlew :prometeu-app:stageStudioInstallation -PstudioInstallationRoot=/absolute/dev-installation
```
In IntelliJ, run/debug `p.studio.app.StudioLauncher` with the `prometeu-app`
runtime classpath and VM option `-Dstudio.installationRoot=/absolute/dev-installation`.
The desktop and client-owned connector are separate JVMs. To debug the latter,
add the development-only VM argument
`-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=127.0.0.1:5005`
before `-cp` in the local MCP entry, restart that MCP process, then use IntelliJ's
**Remote JVM Debug** on localhost:5005. Do not commit this local configuration.
Because manual edits to the managed entry are protected, restore its original
content before using preparation again. Regular registration never enables JDWP.
## External Coding Agents (MCP)
The following authorization workflow belongs to the previous DEV adapter. The new
Play UI does not yet expose a grant/configuration surface. Headless protocol,
task authority, MCP tool schemas and the installed stdio connector retain their
existing entry points.
Studio includes its own `mcp --project <absolute-root>` mode. Configure the native
client once; project grants and desktop restarts no longer require copying ports
or tokens. The initial integration targets Codex on macOS.
1. Install/stage Studio with its bundled Java runtime (see installation above).
New projects prepare the local client entry during scaffolding. Opening an existing project
also prepares its enabled integration automatically; Studio starts the shared
MCP server itself. **DEV → Prepare assistant** retries preparation after resolving
a reported setup conflict. Opening a project does not grant agent control.
2. Open the coding client in the project directory. Trust the project and reload
MCP once if the client requests it. Studio does not alter client approval policy.
Tools can initialize/list even before the desktop is open or access is granted.
3. Open the project in Studio and grant control in DEV (save first if prompted).
Active Debug prevents granting. The connector discovers access automatically.
4. The agent acquires a task, consults project/language/SDK references, edits saved
project files with its native tools and validates through LSP/build. SDK and
external libraries remain read-only.
5. Recover uncertain operations by operationId/clientRequestId lookup within the
same task; never replay build/advance blindly. Explicitly release control when
done. Human reclaim also revokes access; stop direct external file edits separately.
The client invokes the same Studio artifact over stdio. It forwards to Studio's
project-scoped loopback service using protected, transient
`.studio/mcp/connection.json`. The permanent `.codex/config.toml` entry contains
installed Java/classpath/root arguments, not credentials. Both local outputs are
ignored by Git. Unrelated client settings are preserved; tracked or conflicting
Studio entries require deliberate resolution. `.studio/setup.json` preserves
neutral integration intent and existing runtime/editor settings.
After desktop restart, grant again in DEV. Keep the same client session and
configuration; old task identities and operation receipts are not restored.
DEV displays connection separately from project authority. No project-local
launcher, Python transport script or embedded chat is required.
### Reading external source code
VS Code F12 opens SDK/core and admitted libraries as read-only documents, with
hover, continued F12 and syntax highlighting. SDK/core stay bundled; no editorial
copies are created. After a source revision changes or a session ends, navigate
again instead of reusing old positions.
For MCP, use `studio_language_query` with `operation: "definition"`, then pass a
returned `prometeu-source:` URI to `operation: "readExternalSource"`. The response
contains `descriptor` and `text`; hover and definition accept the same URI within
the owning task. Another task cannot reuse it. MCP does not require VS Code open.
External or mixed edit proposals are refused in full. Library installation/cache
management is outside this feature. See the [extension guide](../tools/vscode-extension/README.md).
The production tools cover context, references, task control, LSP,
build/pack, operation lookup/cancellation and headless execution.
Headless requires a runtime installation configured for the project; missing or
incompatible installations fail explicitly. DEV is an
observation panel, not manual Play/input for the agent's session; **Debug** retains
the human testing workflow. Edits are preserved on cancellation; Git/review/recovery
remain the developer's responsibility.
See the [MCP contract](specs/studio/11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md)
for schemas, authorization, limits and delivery boundaries.
### Troubleshooting automation
| Symptom | Action |
| --- | --- |
| Waiting for access / desktop restarted | Open the project and grant again in DEV. Keep the existing client configuration. |
| Stale connection / incompatible catalog | Grant fresh access, or update the installed Studio when versions differ. Do not edit transient credentials. |
| Preparation conflict | Preserve the existing client settings; resolve a tracked/user-owned/edited Studio table explicitly, then prepare again. |
| Acquisition rejected or project busy | Grant control in DEV first; stop manual Debug before granting. Query an existing operation instead of starting another; serialize headless calls. |
| `RUNTIME_UNAVAILABLE` or handshake incompatibility | Check the project's configured runtime installation and its packaged headless command. Studio does not download a substitute. |
| `NO_FRAME_AVAILABLE` | Advance at least one frame before requesting a capture. |
| Advance/page limit rejected | Respect advertised limits and use reference pagination. Runtime's default maximum is 600 frames per advance; requests are not silently clamped. |
| Unknown language or missing reference | Inspect project context and the declared manifest language; use only advertised capabilities/reference IDs. PBS is a creation default, not an unknown-language fallback. |
| Returning control reports cleanup failure | Stop the external client's direct editing separately, then retry DEV reclaim after owned-process cleanup. Do not bypass the lock or restore stale editor buffers. |
Language and SDK references are bundled locally; reading them does not require a
compiler checkout or network download. SDK/external-library changes remain outside
the game-authoring task, even when a reference exposes a limitation.
## Integration Checks
Unit tests run through `./gradlew test`. Process, network, desktop and actual
application/provider composition checks use separate integration tasks, including
fixture subprocesses. These suites remain in Studio; `../tooling` prepares their
environment and orchestrates selected commands.
Integration checks are excluded from the runtime and Studio pipelines.
### Installed Studio Connector
```bash
./gradlew :prometeu-app:installedConnectorTest
```
Checks bundled Java, upgrade/rollback, project paths with spaces, minimal
environment, scaffolding/preparation and JavaFX startup.
### Integrated Play
The product starts with a separate project launcher. Add selects a `prometeu.json`
and remembers the project without opening it; Forget removes only the reference.
New Project opens a five-step wizard using the language catalogue. Successful
creation opens the project through the same shield as an existing project. The
shield follows actual opening steps and remains visible for at least one second,
counted in parallel with preparation. Opening a project does not compile or start
the game. Closing its window stops execution and returns to the launcher.
The launcher inherits presentation preferences and offers **Prometeu Studio > Preferences**
instead of permanent appearance selectors. This dialog also sets the machine-local
runtime default; **Project > Settings** configures an optional override and save
media. Interactive Play freezes the effective runtime for both asset capacity
qualification and launch, leaving inherited project configuration null. Headless
and MCP configuration remains project-specific.
The global Play/Stop button and Pause/Resume toggle stay on the right above the
Gameplay tab, moving together onto a second right-aligned row when navigation
needs the space. State text
lives in the project header. The equal-height footer follows the selected tab and
shows Gameplay's effective scale. Native tabs use stepped upper corners and a flat,
open base joining the content, without a button's lower bevel. Studio identity
appears once in the launcher's menu. Gameplay automatically fits the native frame
to its surface; the optional manual slider
uses 25–400% scale, with scrolling for oversized images. Window geometry is stored
in `~/.prometeu-studio/window-state.json`; the runtime default is stored separately
in `~/.prometeu-studio/runtime-settings.json`. Neither is portable game metadata.
Closing the launcher exits Studio. `./gradlew run` at the root
launches only the product; the independent shell/gallery require their explicit
module commands and do not run after the product closes.
The active tab's gold outline encloses its content with an opening below the tab
header. The product workspace uses a plain surface and equal top/bottom margins;
there is no additional decorative frame around the tabs. The standalone foundation
shell retains its panel. Gameplay contains a vertical SplitPane: game/local scale controls above,
logs below, initially around 80/20. Drag its horizontal divider to prioritize logs
or game. Automatic fitting follows the resulting render area, including while
paused; manual mode preserves the chosen scale and uses scrolling. The split stays
with the open view and is not stored as a project preference. Header/footer stay
outside the split. The outline decoration does not participate in layout or hit testing.
Qualify these windows without a native runtime using disposable projects and
isolated presentation storage:
```bash
./gradlew :prometeu-app:studioProjectsDesktopTest
```
Scene captures and environment metadata are written to
`prometeu-app/build/projects-desktop-captures`. This gate covers the catalogue,
wizard, appearance, geometry, failure feedback and late-session cleanup; the
separate Play gates below exercise the native process and game lifecycle.
Check command position and painting with real Robot mouse events, screen captures
and a repaint reference across themes, locales and text scales:
```bash
./gradlew :prometeu-app:studioControlsDesktopTest
```
Captures and pixel comparisons are written to
`prometeu-app/build/controls-desktop-captures`. The diagnostic fixture retains the
old wrapping layout to measure displacement; the stable-layout gate exercises the
current execution bar. These checks do not replace human confirmation of a reported
artifact that cannot be reproduced on the qualification machine.
Requires a desktop environment and an installed native runtime:
```bash
./gradlew :prometeu-app:studioPlayProcessTest -PstudioRuntimeInstall=/absolute/runtime-install
./gradlew :prometeu-app:studioPlayDesktopTest -PstudioRuntimeInstall=/absolute/runtime-install
```
Add `-PstudioPlayStress=true` for the 30-second presentation/FX-delay/20-cycle
check. Fixtures use a disposable copy of `test-projects/pong`. No external port
checkout is required. Changed native executables require renewed qualification
as described above.
### Headless Runtime and Application Composition
Use an extracted runtime distribution:
```bash
./gradlew :prometeu-app:headlessProcessTest -PstudioRuntimeInstall=/absolute/path/to/runtime
```
Exercises the real runtime, installed PBS examples, canonical PNGs, reset/reboot,
cancellation and process cleanup, plus saved-file LSP/build corrective loops.
The task requires the supplied runtime installation.
### MCP and DEV Desktop Integration
This check exercises the retained DEV adapter. It requires a POSIX desktop and
free port 7777:
```bash
./gradlew :prometeu-app:headlessMcpDesktopTest -PstudioRuntimeInstall=/absolute/path/to/runtime --max-workers=2
```
The HTTP client drives LSP, build and a fixed input timeline; output and visible
DEV pixels are compared with a separate direct-JSONL runtime process. Scenarios
include reset, cancellation, disconnect/reconnect, revocation, project/app closure,
crash, forced shutdown and return to manual Debug. Only test-owned processes are
terminated or suspended. After a forced-shutdown error, a second explicit reclaim
can acknowledge completed cleanup; control stays locked until cleanup is confirmed.
These commands describe available checks. Record actual runs, environment,
results, acceptance evidence and pending investigations in the owning AIE Work.