version: "1.0.0" name: ada-build-run description: Build, test, run, stop, and diagnose Ada projects on their supported destination. allowed-tools: terminal, editor.project.context, editor.build.start, editor.test.start, editor.play.start, editor.task.status, editor.task.stop, editor.output.read, runtime.pause, runtime.resume, runtime.step_frame, trace.status, profiler.live_snapshot

Ada Build and Run

• Use editor.project.context to check which project and document are open before choosing a build or run command. The editor MCP exposes project context and scene authoring; use the existing build/run workflow for compilation and tests.
• Prefer editor.build.start, editor.test.start, and editor.play.start to use the editor's selected destination and native AdaScript/SwiftPM flow. Poll editor.task.status, then read the editor or game output stream with editor.output.read.
• Use editor.task.stop for a running build, test, run, debugger, player, or Play Mode session.
• Save dirty documents before starting a build or run.
• AdaScript-only projects build in process and may run on macOS or iPadOS. SwiftPM build, test, and run is a macOS workflow in AdaEditor.

Testing an AdaScript project

editor.test.start runs AdaScript tests in process, with no SwiftPM. Write a test as a free function marked @test (optionally @test("display name")) with no parameters, either beside the code in any .ada file (sees that file's private names) or in a file under Tests/ (sees public names only, never shipped).

Files under Tests/ see public names only and must import what they use, with a trailing semicolon: import { Flight } from "../Sources/Main.ada";. A missing import fails the run with Tests/X.ada:3:10: 'Flight' is declared in 'Sources/Main.ada'; import it with ....

@test("flap lifts the bird")
func flapLifts() {
    var f = Flight();
    f.tick(0.016, true, false);
    expect(f.y > 0.0);
}

• Assertions: expect(cond), expectEqual(a, b), expectNear(a, b, tolerance), expectNil(x), fail(message); they record a failure and the test continues. require(cond) records and stops the test. Use TestWorld() (spawn, insert, read, count, run(ticks), runSystem(System, ticks), advance(seconds)) to test systems against a fresh ECS world.
• Do not keep state in module-level variables across tests: numbers, booleans, strings and null are restored after each test, but lists and maps are shared.
• Pass filter (a substring of the function name or display name) to run a subset. A project with no @test, or a filter that matches nothing, is refused or fails with that reason; it is not a pass.
• Poll editor.task.status: status is ready when every test passed and failed otherwise, and adaScriptTests has passed, failed, total, finished and a failures list. Then read editor.output.read (editor source): one PASS/FAIL line per test, each failure followed by path:line:column: message pointing at the failing assertion. A compile error in any source or test file fails the run with its location.
• Each test has a 30 second limit, checked at function entries and loop iterations; a runaway loop fails that test with "timed out" and the rest still run.
• The result is evidence of logic only. Passing tests do not prove rendering, input feel or audio; combine with editor.play.start and visual verification.
• Prefer the narrowest build or test that exercises the changed path, then broaden when the change crosses modules.
• Read structured diagnostics and complete output before editing again. Separate code failures from toolchain, network, storage, or platform failures.
• Stop an existing run before replacing its runtime state. Report the exit or stop reason.