Files
prometeu-studio/docs/development.md
T
bquarkz 23522f7589
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/head There was a failure building this commit
docs(studio): keep README focused on project onboarding
2026-11-19 17:58:22 +00:00

11 KiB

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 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:

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:

./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:

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:

./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.

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 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

./gradlew :prometeu-app:installedConnectorTest

Checks bundled Java, upgrade/rollback, project paths with spaces, minimal environment, scaffolding/preparation and JavaFX startup.

Integrated Play

Requires a desktop environment and an installed native runtime:

./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:

./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:

./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.