feat: modes, environments, and a plugin host

[monikon22]

Thanks for creating v3-dev — this is the first of the six, targeted there.

The biggest change in the series, and the one everything after it depends on. It replaces the assumption that a run means "one Paper server that plugwright downloaded and started" with a registry of environment modes, and gives the runner a real extension point.

Rebased onto v3-dev at 8a8b570 (so it sits directly on top of the merged #45), no conflicts, tsc --noEmit clean on the runner package. The two follow-up commits you took in #45 touch utils.ts and wrappers.ts, neither of which this PR modifies.

What changes

The gradle plugin splits into modules. plugwright-api holds the types a third-party mode compiles against, plugwright-core the shared machinery, plugwright-local the mode that downloads and runs Paper, plugwright-external a mode that connects to a server it does not own. plugwright-bundle is the module published under the plugin id; its jar embeds the others, which have no coordinates of their own.

A build declares environments instead of one server.

plugwright {
    primaryEnvironment.set("local")

    environments {
        create("local", LocalMode) {
            minecraftVersion.set("1.21.11")
            acceptEula.set(true)
        }
        create("stand", ExternalMode) { /* a server started by hand */ }
    }
}

PlugwrightMatrixTask runs the suite across them, writes JSON and JUnit reports per environment, and filters on requires and environments.

Configuration moves to a config.json transport. The gradle side writes what the runner needs; the runner stops reading gradle-shaped properties. Secrets travel as references and are resolved when they are used, not when the file is written.

The runner loses its module-level singletons. Session owns what was global, and Environment / ServerConsole abstract "the server" so a mode that owns no process can still op a player and read the console. ExternalMode does that through an admin bot and an account pool, with ping and cleanup entry points so an unowned server can be checked and put back.

Message buffers are the exception, and that is the one place where this series changed shape after your c4a89a4 — see below.

A plugin host. Hooks, fixtures, custom matchers, inherited tests and a cleanup journal, so a plugin can extend the test context rather than only observe it.

Meeting c4a89a4 and d0289e6

Both of those are addressed rather than merged around, and one of them changed my mind.

The message buffer is yours, not mine. An earlier draft of this PR moved the global messageBuffer onto Session. That was the wrong scope and your commit is what made it obvious: per-session is still one buffer shared by every bot, so expect(playerA).toHaveReceivedMessage(...) could be satisfied by something player B heard. Renaming the global is not fixing it.

So the buffer is per PlayerWrapper, as you had it, and Session keeps only what is genuinely one-per-session — the bot list, the disconnect lifecycle, consoleLog. Three things fell out:

• AdminBotConsole was hand-rolling a private buffer and its own message listener specifically to stay out of the shared one, and PlayerWrapper.join() then registered a second listener on the same bot. It now reads player.messageBuffer and the duplicate is gone.
• The AuthMe plugin's prompt-matching reads its own player's buffer, so two bots authenticating at once can no longer answer each other's prompt (that lands in PR 2).
• disconnectAllBots delegates to disconnectBot instead of duplicating its promise logic, so your removeAllListeners cleanup happens on every path rather than one of them. PR 5 extends the same method with a keep list; it extends the delegating version.

There is one case your patch does not reach, because the feature that creates it is in PR 5: "clear on rejoin" never fires for a player checked out under stay, which never left and so never rejoins. That is fixed there, not here.

The Gradle refactor mostly agrees with this series already. Shared task setup, typed TaskProviders, the verification group and the banner all exist here through AbstractNodeTask and PlugwrightCompileTestsTask — arrived at independently, so no conflict worth reporting.

Two that did need a decision:

• The IDEA sync trigger would have been dropped silently by the module split, since it hangs off a task that no longer exists under that name. It is carried over in its own commit, still behind plugins.withId("idea"), and now triggers the compile task — so a sync installs and compiles.
• Your up-to-date checks on plugwrightNpmInstall are not carried over, and I want to flag that rather than have you find it. That task merged into PlugwrightCompileTestsTask, which declares outputs.upToDateWhen { false } on purpose: its output depends on node_modules and on the installed runner package, neither of which is a declared input, so claiming up-to-date risks serving stale compiled specs. Making it properly incremental means declaring those inputs, which is worth doing and is not something I wanted to rush inside a rebase.

Where to start reading

plugwright-api first — it is small and it is the contract. Then RunnerConfigWriter.kt and runner-package/lib/config.ts for the two ends of the transport, then session.ts.

What it does not do

No behaviour changes for an existing single-environment build. The pre-3.0 flat properties (minecraftVersion, jvmArgs, acceptEula, …) still work and still describe an implicit local environment; they are marked deprecated and read only when there is no environments { } block.

The mode API and the plugin host contract are both public surface, and I do not think either is finished — that is the point of building them on v3-dev rather than shipping them to 2.x users.

How to merge this one

Please use "Create a merge commit" or "Rebase and merge" — not "Squash and merge".

PRs 2 through 6 are stacked on this branch's exact commits. A squash would replace all 13 with one new commit, and then every later PR would carry the same changes under different SHAs: PR 2 would show ~85 files instead of its own 49, and I would have to rebase-and-resolve the whole remaining stack by hand after each merge. A merge commit (the way #45 went in) or a rebase-merge both keep the SHAs, and PR 2 then shows only its own 15 commits against v3-dev.

If you would rather have a tidier history on v3-dev, squashing is fine on the last one — by then there is nothing stacked behind it. Or squash the whole series into one commit when v3-dev eventually merges into master, which gets you a clean master without breaking the stack along the way.

Once this is in, I will retarget PR 2 to v3-dev and open it. Same for the rest, in order.

Part of #46.

[Drownek]

Thanks for opening this, @monikon22, the architecture direction looks good.

One problem though: I can't get IntelliJ to sync the project. It fails with:

FAILURE: Build failed with an exception.
* What went wrong:
Failed to apply plugin class 'org.gradle.plugins.ide.idea.IdeaPlugin'.
Cannot run Project.afterEvaluate(Action) when the project is already evaluated.

Probably the IDEA sync trigger got carried over in the refactor and now it's firing after the project's already evaluated.

Separate thing: Gradle's warning that the Kotlin plugin is loaded multiple times with explicit versions across the new subprojects (plugwright-api, plugwright-bundle). Usually cleaner to declare the version once in the root with apply false and skip it in the subprojects.

If the IDEA sync trigger is more trouble than it's worth, just drop it for now, no big deal. Let me know when it's updated.

[monikon22]

Thanks for testing it, both are fixed.

IDEA sync. The trigger itself was fine, the afterEvaluate wrapped around it wasn't. IntelliJ applies the idea plugin to a project that has already been evaluated, so the plugins.withId("idea") callback fires after configuration is done and Project.afterEvaluate throws from inside IdeaPlugin.apply. That's why the message names the IDEA plugin instead of us. The frame under it:

at me.drownek.plugwright.PlugwrightCorePlugin$registerIdeaSyncTrigger$1.execute(PlugwrightCorePlugin.kt:85)

It now wires afterSync right away when the project is already evaluated, and defers only while configuration is still running:

project.plugins.withId("idea") {
    project.pluginManager.apply("org.jetbrains.gradle.plugin.idea-ext")
    if (project.state.executed) {
        wireIdeaSyncTrigger(project, plugwrightCompileTests)
    } else {
        project.afterEvaluate { wireIdeaSyncTrigger(project, plugwrightCompileTests) }
    }
}

One thing worth flagging: this isn't new in this PR. The same withId("idea") { ... afterEvaluate { ... } } shape sits on v3-dev today, in PlugwrightPlugin.kt lines 345-355. I reproduced the identical failure on a clean worktree at 8a8b570 using an init script that applies idea from gradle.projectsEvaluated, which is the moment the IDE applies it. The module split carried the bug into plugwright-core, it didn't create it. So I kept the trigger instead of dropping it, since it now survives both paths.

Kotlin plugin. Done the way you suggested. kotlin-dsl is declared once in the root build with apply false and handed to the modules from the shared subprojects { } block, and the five module scripts no longer declare it. The warning is gone from ./gradlew build.

Verification: the sync simulation passes now and fails without the fix; the trigger really does register in both cases, with taskTriggers.toMap() reporting afterSync: plugwrightCompileTests whether idea is applied before or after evaluation; the merged bundle jar is unchanged. Also confirmed in a real IntelliJ sync on the example project.

Two commits on the branch: 86fd6fb for the sync trigger, 5bdcc6d for the Kotlin plugin.

[Drownek]

Merging this into v3-dev as agreed
I'll bump the version to 3.0.0-dev.0 on the branch right now. Ready for second PR
whenever you are