268 lines
14 KiB
Markdown
268 lines
14 KiB
Markdown
# 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/`: workflow artifacts for agendas, decisions, plans, and lessons.
|
|
- `test-projects/`: sample workspaces used for local development and tests.
|
|
|
|
## 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](tools/vscode-extension/README.md).
|
|
|
|
### 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.
|
|
|
|
The packaged automated gate checks bundled Java, upgrade/rollback, project paths
|
|
with spaces, minimal environment, scaffold/preparation and JavaFX startup:
|
|
|
|
```bash
|
|
./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](docs/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.
|
|
|
|
The real headless process adapter and task-service composition can be verified
|
|
using an extracted runtime distribution:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
./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](discussion/lessons/DSC-0070-studio-persistent-mcp-connector/LSN-0077-integrated-mcp-stable-setup-and-ephemeral-access.md) 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](discussion/lessons/DSC-0068-studio-headless-runtime-ai-first/LSN-0076-ai-first-studio-through-shared-authority-and-headless-evidence.md).
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
./gradlew projects
|
|
```
|
|
|
|
Run the desktop application:
|
|
|
|
```bash
|
|
./gradlew :prometeu-app:run
|
|
```
|
|
|
|
Run the test suite:
|
|
|
|
```bash
|
|
./gradlew test
|
|
```
|
|
|
|
Generate the aggregated coverage report:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
- `docs/specs/compiler/`: shared compiler specifications
|
|
- `docs/specs/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.
|