diff --git a/README.md b/README.md index b4cfafff..339e013f 100644 --- a/README.md +++ b/README.md @@ -1,337 +1,100 @@ # 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-2`: the default human-facing frontend and presentation foundation. -- `prometeu-studio-ui-javafx`: retained previous adapter and compatibility qualification surfaces. -- `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](../README.md) using -[AI Engineering](../.ai-engineering/README.md). - -## Current Product Shape - -The normal and installed application opens the new project chooser. Open an existing -project, choose a qualified runtime installation, then use Play, Pause, Resume and -Stop. Close the project before opening another. A save-capable game requires an -existing development save image or an explicitly disposable session. - -Play prepares compiler/assets into the cartridge directory and starts an owned -native runtime process whose frames appear inside Studio. Zoom is x1/x2/x4 in -logical pixels with scrolling. Minimizing or switching applications pauses; -returning requires manual Resume. Closing stops the game, subject to save protection. -Play does not create a PMC or a distributable build. - -This first frontend slice does not mount editors, Assets/DEV/Shipper workspaces, -AI prompts/configuration or breakpoint debugging. Their existing service contracts, -headless runtime and MCP adapters remain separately tested. The previous DEV guide -below describes retained adapter behavior, not controls available in the new UI. -See the [integrated Play contract](docs/specs/studio/14.%20Integrated%20Play%20Specification.md). - -## 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. This omission does not -change the deterministic headless protocol, task authority, MCP tool schemas or -installed stdio connector; their process and adapter qualification gates remain. - -Studio includes its own `mcp --project ` 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: /current/runtime/bin/java -args: ["-cp", "/current/lib/*", "p.studio.app.StudioLauncher", "mcp", "--project", ""] -``` - -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). +It combines a JavaFX application with compiler integration, asset packing, project +services and runtime orchestration in a multi-module Java/Gradle build. ## Requirements -- JDK 25 for local compilation/tests and the bundled product runtime (Gradle 9.3.1) -- Gradle wrapper (`./gradlew`) included in the repository +- JDK 25 for compilation, tests and the bundled application runtime +- The included Gradle wrapper (Gradle 9.3.1) - A desktop environment capable of running JavaFX +- A qualified native Prometeu runtime installation for running games -## Common Commands +## Getting Started -Run the full project graph listing: - -```bash -./gradlew projects -``` - -Run the desktop application: +Run these commands from the Studio repository root: ```bash ./gradlew :prometeu-app:run ``` -The new UI is the default. `:prometeu-studio-ui-javafx-2:run` and `:gallery` remain -separate foundation demonstrations, without a backend or a project. +Open an existing project from the project chooser and select a qualified runtime +installation. Use Play, Pause, Resume and Stop to run the game inside Studio. +Games with saves require an existing development save image or an explicitly +disposable session. Close the project before opening another. -Opt-in integrated Play qualification (desktop/installed native runtime required): +The default frontend is `prometeu-studio-ui-javafx-2`. It provides project opening +and integrated Play; editors, Assets/DEV/Shipper workspaces and MCP grant controls +are outside its current UI. Play prepares a cartridge directory for execution; +distribution/export is a separate concern. -```sh -./gradlew :prometeu-app:studioPlayProcessTest -PstudioRuntimeInstall=/absolute/runtime-install -./gradlew :prometeu-app:studioPlayDesktopTest -PstudioRuntimeInstall=/absolute/runtime-install -``` +See the [development guide](docs/development.md) for installation, runtime +qualification, IntelliJ setup, MCP integration and integration test commands. +The [integrated Play specification](docs/specs/studio/14.%20Integrated%20Play%20Specification.md) +defines execution, input and save behavior. -Add `-PstudioPlayStress=true` for the 30-second presentation/FX-delay/20-cycle gate. -The headless visual evidence pilot uses a disposable copy of `test-projects/pong`. -Integration fixtures belong to this repository; no external port checkout is -required. A runtime's three executable identities must match a distributed -capacity profile; rebuilding a native binary does not automatically requalify it. - -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-` 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. - -Run the test suite: +## Build and Test ```bash +./gradlew build ./gradlew test -``` - -`test` runs unit tests and excludes JUnit `@Tag("integration")`. Integration -includes process/network/desktop qualification and real application or provider -composition, including fixture subprocesses. Existing integration suites remain -in this repository; `../tooling` prepares their environment and orchestrates -selected integration commands and builds. They are currently excluded from the -runtime and Studio pipelines; the opt-in commands above are separate checks. -Consolidated JaCoCo uses only the unit `test.exec` files. - -Generate the aggregated coverage report: - -```bash ./gradlew jacocoTestReport ``` -## Repository Reading Guide +`test` runs unit tests and excludes JUnit `@Tag("integration")`. The aggregated +JaCoCo report uses unit test results. Process, network and desktop checks have +[separate opt-in commands](docs/development.md#integration-checks). -If you are new to the codebase, this order is usually the fastest path: +Stage a complete installation with its bundled Java runtime: -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. +```bash +./gradlew :prometeu-app:stageStudioInstallation +``` -## Specs And Architecture +The default installation root is +`~/Library/Application Support/Prometeu/Studio`; `current` selects its active +version. See [installation and development](docs/development.md#installation-and-intellij-development) +for an isolated development installation. -Important reference surfaces: +## Repository Structure +| Area | Responsibility | +| --- | --- | +| `prometeu-app` | Spring Boot composition, concrete adapters, packaging and the `p.studio.app.StudioLauncher` entry point | +| `prometeu-studio-api` | Toolkit-neutral Studio contracts and operations | +| `prometeu-studio-core` | JavaFX-free project, session, asset, shipper and execution services | +| `prometeu-studio-ui-javafx-2` | Default frontend and presentation foundation | +| `prometeu-studio-ui-javafx` | Previous frontend retained for adapter compatibility checks | +| `prometeu-compiler` | Compiler core, build pipeline, frontend APIs and PBS frontend | +| `prometeu-packer` | Asset packing APIs and implementation | +| `prometeu-infra` | Shared infrastructure | +| `test-projects` | Sample projects and integration fixtures | +| `docs` | Technical guides, specifications and architecture references | +| `discussion/lessons` | Published engineering lessons and their assets | + +Run `./gradlew projects` to list the complete module graph. + +Start with `prometeu-app` for application bootstrap, then read +`prometeu-studio-api` and `prometeu-studio-core` for contracts and services. +The [JavaFX 2 module guide](prometeu-studio-ui-javafx-2/README.md) covers the current +frontend. Follow the compiler and packer modules for their respective pipelines. + + + +## Documentation + +- [Development guide](docs/development.md): installation, MCP, troubleshooting and integration checks - [Specification guide](docs/specs/README.md): domain ownership and reading order -- [General compiler](docs/specs/compiler/README.md): shared compiler specifications -- [PBS](docs/specs/compiler-languages/pbs/README.md): language and SDK specifications -- [Studio](docs/specs/studio/README.md): shell, workspaces and integration contracts -- [Packer](docs/specs/packer/README.md): packer specifications -- `docs/vm-arch/`: VM and ISA architecture references +- [Studio](docs/specs/studio/README.md): application, services and integration contracts +- [Compiler](docs/specs/compiler/README.md): shared compiler contracts +- [PBS](docs/specs/compiler-languages/pbs/README.md): language and SDK +- [Packer](docs/specs/packer/README.md): asset and packaging contracts +- [VM architecture](docs/vm-arch/README.md): VM/ISA references and provenance +- [VS Code extension](tools/vscode-extension/README.md): language tooling and external source navigation -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. +Engineering discussions, decisions, plans, build/acceptance results and pending +investigations belong to the enclosing +[Prometeu Engineering workspace](../README.md) in +[AI Engineering](../.ai-engineering/README.md). See [AGENTS.md](AGENTS.md) before +contributing. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 00000000..cbf872c0 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,213 @@ +# 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-` 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: /current/runtime/bin/java +args: ["-cp", "/current/lib/*", "p.studio.app.StudioLauncher", "mcp", "--project", ""] +``` + +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 ` 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 + +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. diff --git a/docs/specs/studio/14. Integrated Play Specification.md b/docs/specs/studio/14. Integrated Play Specification.md index c4a97b41..ad836df8 100644 --- a/docs/specs/studio/14. Integrated Play Specification.md +++ b/docs/specs/studio/14. Integrated Play Specification.md @@ -140,7 +140,7 @@ umbrella distribution produced by `runtime/scripts/local-dist.sh`, including rea Pong Play and the deterministic headless process. Capacity qualification identifies the dispatcher and both native backends as one exact bundle; multiple releases may share an unchanged dispatcher. The explicit qualification command is documented in -the [Studio README](../../../README.md). +the [development guide](../../development.md#native-runtime-installation-and-qualification). Earlier presentation performance measurements used debug native binaries. Windows/Linux, release performance, physical HiDPI pixel alignment, and human