bquarkz fa37d0d0c7
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
chore: retire Discussion Framework workflow and retain lessons
2026-11-16 16:45:34 +00:00
2026-04-07 06:17:51 +01:00
2026-03-24 13:42:13 +00:00
2026-04-07 06:17:51 +01:00
2026-03-24 13:42:13 +00:00
2026-03-24 13:42:13 +00:00
2026-03-24 13:42:13 +00:00

Prometeu Studio

Prometeu Studio is the desktop development environment for the Prometeu toolchain.

This repository packages the Studio shell together with the embedded services it depends on: compiler pipeline integration, asset packing, runtime/debug orchestration, and project-local Studio state. The current implementation is a Java/JavaFX multi-module Gradle build.

What Lives Here

The root project is a monorepo with these main areas:

  • prometeu-app: Spring Boot non-web composition, concrete adapters, packaging, and JavaFX entry point (p.studio.app.StudioLauncher).
  • prometeu-studio-api: toolkit-neutral Studio contracts and operation surfaces.
  • prometeu-studio-core: JavaFX-free project, session, assets, shipper, runtime, and execution services.
  • prometeu-studio-ui-javafx: the current human-facing JavaFX adapter.
  • prometeu-packer: embedded packer APIs and implementation used by Studio.
  • prometeu-compiler: compiler core, build pipeline, frontend APIs, and the PBS frontend.
  • prometeu-infra: shared infrastructure used across modules.
  • docs/: normative specifications and architectural references.
  • discussion/lessons/: published engineering lessons and supporting assets.
  • test-projects/: sample workspaces used for local development and tests.

Engineering discussions, decisions, plans and execution evidence are maintained in the enclosing Prometeu Engineering workspace using AI Engineering.

Current Product Shape

The Studio shell currently organizes the product around four workspaces:

  • Assets
  • Debug
  • DEV (external-agent authorization and observation)
  • Shipper

At runtime, the app boots an embedded packer, restores project-local Studio state, and opens the Studio launcher window. Project creation currently scaffolds a Prometeu workspace with prometeu.json, src/, assets/, build/, cartridge/, .workspace/, and local Studio metadata.

External Coding Agents (MCP)

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 below). 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.

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.

The packaged automated gate checks bundled Java, upgrade/rollback, project paths with spaces, minimal environment, scaffold/preparation and JavaFX startup:

./gradlew :prometeu-app:installedConnectorTest

The current production tools cover context, references, task control, LSP, build/pack, operation lookup/cancellation and headless execution (17 tools). 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.

The real headless process adapter and task-service composition can be verified using an extracted runtime distribution:

./gradlew :prometeu-app:headlessProcessTest -PstudioRuntimeInstall=/absolute/path/to/runtime

This gate builds an installed PBS example, launches the actual runtime, checks canonical PNGs and explicit reset/reboot, cancels an advance and verifies process cleanup. It also runs the actual app composition through saved-file LSP queries, rebuilds and corrective loops after compile errors and guest faults. It does not download a runtime or substitute a protocol fixture.

To verify the complete HTTP-to-runtime-to-DEV image path, run this separate gate in a desktop environment:

./gradlew :prometeu-app:headlessMcpDesktopTest -PstudioRuntimeInstall=/absolute/path/to/runtime --max-workers=2

It opens the real DEV view, grants control, uses an HTTP MCP client to query LSP, edit/build the installed PBS example and execute a fixed input timeline. PNG bytes, frame identities, state and fault are compared with a separate direct-JSONL runtime process; every decoded ImageView pixel and its visible identity/stale label are checked. Reset, fresh-session repetition and rebuild are included. This automated client is not the external coding-agent acceptance gate.

The same suite also exercises cancellation, disconnect/reconnect, revocation, project/app closure, crash and forced shutdown, corrective builds, and return to the real manual Debug host. These scenarios require a POSIX desktop (validated on macOS ARM64) and free port 7777. Only processes created by the test are killed or suspended. After a forced-shutdown error, an explicit second reclaim can acknowledge completed cleanup; control stays locked until cleanup is confirmed.

Follow-ups after the AI-first implementation

The following findings are recorded for investigation after implementation; they are not considered fixed by the passing integration tests:

  • PBS/LSP SDK navigation: the historical probe of the former Input.pad() API returned no location; the current input API is Pad/Button and Touch. Project-source navigation and indexed SDK reference reads work. Investigate SDK symbol resolution separately; an empty definition result is not evidence of missing runtime support or permission to edit the SDK.
  • Build tooling: the validation environment's JDK 25 triggers Kotlin's target-24 fallback and Java/Kotlin target compatibility warnings in buildSrc. The targeted regression passes, but the toolchain/target alignment needs separate review.

Cross-platform desktop coverage remains a validation boundary, not a confirmed product defect. Baseline HTTP desktop acceptance covers macOS ARM64 and Codex CLI only. The integrated stdio flow completed its separate acceptance gates through automated validation and user-confirmed native-client, graphical-launch and IntelliJ checks; see LSN-0077 for evidence provenance.

The first real Codex CLI acceptance run exercised editing, LSP, build/pack, input, 1,110 frames, native MCP images and explicit release. The developer confirmed the DEV result and successfully ran the edited game using manual Debug Play afterward. Additional follow-ups from that run: clearer errors for oversized reference pages, guidance for sequential headless queries after BUSY, and easier discovery of framebuffer dimensions. Capture before the first completed frame correctly returns NO_FRAME_AVAILABLE; it is not a runtime defect. Noninteractive clients must also provide an approval path for MCP work calls; the acceptance used Codex's approval review with a project-scoped workspace-write sandbox.

The completed baseline's architecture, acceptance evidence and post-implementation follow-ups are consolidated in LSN-0076.

Requirements

  • JDK 21 or newer recommended for local development
  • Gradle wrapper (./gradlew) included in the repository
  • A desktop environment capable of running JavaFX

Common Commands

Run the full project graph listing:

./gradlew projects

Run the desktop application:

./gradlew :prometeu-app:run

Run the test suite:

./gradlew test

Generate the aggregated coverage report:

./gradlew jacocoTestReport

Repository Reading Guide

If you are new to the codebase, this order is usually the fastest path:

  1. Start at prometeu-app to see application bootstrap.
  2. Read prometeu-studio-api and prometeu-studio-core for Studio contracts and application services.
  3. Read prometeu-studio-ui-javafx for the current shell, workspaces, and human-facing flows.
  4. Read prometeu-app for Spring composition and provider gateways.
  5. Read prometeu-packer for asset and packaging boundaries.
  6. Read prometeu-compiler when you need compiler or PBS language behavior.

Specs And Architecture

Important reference surfaces:

  • Specification guide: domain ownership and reading order
  • General compiler: shared compiler specifications
  • PBS: language and SDK specifications
  • Studio: shell, workspaces and integration contracts
  • Packer: packer specifications
  • docs/vm-arch/: VM and ISA architecture references

These documents are the long-term normative source for behavior and contracts. When code and docs diverge, fix the divergence explicitly instead of relying on tribal knowledge.

S
Description
No description provided
Readme
15 MiB
Languages
Java 94.5%
Rust 3%
Python 1%
TypeScript 0.6%
CSS 0.6%
Other 0.3%