Plugwright v3.0.0

.env.example

@@ -0,0 +1,33 @@
+# Settings for publishing to a registry other than the public ones. Copy to `.env` and fill
+# in what applies; `.env` is ignored by git so the passwords stay out of the repository.
+#
+# None of this is needed for a public release. `npm run publish:packages` with nothing set
+# publishes to npmjs.com, and `./gradlew publishToPublicRepository` publishes the plugin to
+# the Gradle Plugin Portal using the credentials that plugin already looks for
+# (GRADLE_PUBLISH_KEY and GRADLE_PUBLISH_SECRET).
+
+# --- npm packages -------------------------------------------------------------------------
+# Where `npm run publish:packages` sends @plugwright/runner and the plugin packages.
+# Leave the registry unset to publish to npmjs.com instead.
+PLUGWRIGHT_NPM_REGISTRY=https://registry.example.com/repository/npm-hosted/
+PLUGWRIGHT_NPM_USER=
+PLUGWRIGHT_NPM_PASSWORD=
+
+# Optional. The dist-tag to publish under, and the npm access level.
+# PLUGWRIGHT_NPM_TAG=latest
+# PLUGWRIGHT_NPM_ACCESS=public
+
+# --- gradle plugin ------------------------------------------------------------------------
+# Where `./gradlew publishToPrivateRepository` sends the plugin. The same three values can be
+# given as gradle properties instead: plugwright.publish.url, .user and .password.
+# Leave the user and password empty for a repository that accepts anonymous deploys.
+#
+# Naming a URL here is what turns private publishing on. Without one the task succeeds and
+# publishes nothing, so leaving this whole section blank is a valid setup.
+PLUGWRIGHT_PUBLISH_URL=https://repo.example.com/repository/maven-releases/
+PLUGWRIGHT_PUBLISH_USER=
+PLUGWRIGHT_PUBLISH_PASSWORD=
+
+# Optional. Force either destination off, whatever the rest of this file says.
+# PLUGWRIGHT_PUBLISH_PUBLIC_ENABLED=false
+# PLUGWRIGHT_PUBLISH_PRIVATE_ENABLED=false

.gitattributes

@@ -0,0 +1 @@
+*.sh text eol=lf

.github/workflows/ci.yml

@@ -13,21 +13,116 @@ on:
       - 'docs/**'
       - 'docs.json'
       - '**/*.md'
+  workflow_dispatch:
+    inputs:
+      mc_version:
+        description: 'Minecraft version to test'
+        required: true
+        default: '1.21.11'
+        type: choice
+        options:
+          - '1.21.11'
+          - '26.1.2'
+      java_version:
+        description: 'Java version'
+        required: true
+        default: '21'
+        type: choice
+        options:
+          - '21'
+          - '26'
+      run_stand:
+        description: 'Run external stand server tests'
+        required: true
+        default: true
+        type: boolean
 
 jobs:
   test-example-plugin:
     if: "!contains(github.event.head_commit.message, 'skip-ci')"
     runs-on: ubuntu-latest
+    env:
+      GRADLE_OPTS: "-Dorg.gradle.daemon=false"
+      MC_VERSION: ${{ inputs.mc_version || '1.21.11' }}
+      JAVA_VERSION: ${{ inputs.java_version || '21' }}
 
     steps:
       - uses: actions/checkout@v4
-      - name: Build runner-package
+      # The example links all three by path, and npm cannot build a linked package: it packs
+      # the directory into a staging copy that never gets its dev dependencies.
+      - name: Build the local npm packages
         run: |
-          cd runner-package
-          npm install
-          npm run build
+          npm run install:packages
+          npm run build:packages
       - uses: drownek/plugwright-action@v1
         with:
-          java-version: "21"
+          java-version: ${{ inputs.java_version || '21' }}
           node-version: "24"
           working-directory: "./example_plugin"
+
+  test-example-plugin-stand:
+    if: "!contains(github.event.head_commit.message, 'skip-ci') && (inputs.run_stand == null || inputs.run_stand == true)"
+    runs-on: ubuntu-latest
+    env:
+      GRADLE_OPTS: "-Dorg.gradle.daemon=false"
+      MC_VERSION: ${{ inputs.mc_version || '1.21.11' }}
+      JAVA_VERSION: ${{ inputs.java_version || '21' }}
+      # Test-only credentials for the Paper server this job starts and tears down itself.
+      PLUGWRIGHT_RCON_PASSWORD: plugwright
+      PLUGWRIGHT_BOT_PASSWORD: plugwright
+
+    steps:
+      - uses: actions/checkout@v4
+      # Same duplicated build as test-example-plugin: this job runs on its own runner, in
+      # parallel with it, so it can't share that job's npm install/build output.
+      - name: Build the local npm packages
+        run: |
+          npm run install:packages
+          npm run build:packages
+      # Running in parallel with test-example-plugin means this job can't reuse its
+      # generated/local/run/ either - provision the same Paper server here instead of just
+      # running plugwrightTest, which would also run (and duplicate) the local suite.
+      # plugwrightCompileTests is the other half: plugwrightPingStand/plugwrightTestStand
+      # don't depend on it themselves (ExternalMode assumes the stand is already up, nothing
+      # to provision - see registerTasks in ExternalMode.kt), they just expect node_modules
+      # to already have what npm(...) plugin refs and console { rcon {} } need.
+      - uses: drownek/plugwright-action@v1
+        with:
+          java-version: ${{ inputs.java_version || '21' }}
+          node-version: "24"
+          working-directory: "./example_plugin"
+          gradle-args: plugwrightProvisionLocal plugwrightCompileTests
+      # generated/ is gitignored, so start.sh - the launcher example_plugin/README.md tells
+      # developers to hand-write - never made it into the provisioned run dir. Copy in the
+      # tracked copy.
+      - name: Start the stand Paper server
+        working-directory: ./example_plugin/src/test/e2e/generated/local/run
+        run: |
+          cp "$GITHUB_WORKSPACE/example_plugin/src/test/e2e/stand-run/start.sh" .
+          chmod +x start.sh
+          nohup ./start.sh > stand-server.log 2>&1 &
+          echo $! > stand-server.pid
+      - name: Wait for the stand server
+        working-directory: ./example_plugin/src/test/e2e/generated/local/run
+        timeout-minutes: 2
+        run: tail -n +1 -f stand-server.log | grep -q -m 1 'Done'
+      - name: Verify authentication (Ping)
+        working-directory: ./example_plugin
+        run: ./gradlew plugwrightPingStand
+      - name: Run the stand suite
+        working-directory: ./example_plugin
+        run: ./gradlew plugwrightTestStand
+      - name: Stop the stand Paper server
+        if: always()
+        working-directory: ./example_plugin/src/test/e2e/generated/local/run
+        run: |
+          [ -f stand-server.pid ] && kill "$(cat stand-server.pid)" 2>/dev/null || true
+      - name: Upload stand server log
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: stand-server-log
+          path: |
+            example_plugin/src/test/e2e/generated/local/run/stand-server.log
+            example_plugin/build/reports/plugwright/stand.*
+          if-no-files-found: ignore

.github/workflows/release.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write      # for creating GitHub releases
-      id-token: write      # required for OIDC trusted publishing
+      id-token: write      # signs the provenance attestation
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -31,11 +31,19 @@ jobs:
       - name: Upgrade npm
         run: npm install -g npm@11.5.1
 
-      - name: Publish NPM package
-        working-directory: runner-package
+      # The plugin packages link the runner through `file:../runner-package`, so they are
+      # installed together rather than one directory at a time. Each package builds itself
+      # from `prepublishOnly`, and the script publishes all three.
+      - name: Publish NPM packages
+        env:
+          # A trusted publisher is configured per package, and no name under @plugwright
+          # exists yet, so there is nothing for OIDC to authenticate against on the first
+          # release. A granular token scoped to the org carries it; once all three names
+          # exist, `npm trust` takes over and this block comes out.
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
-          npm ci
-          npm publish --access public --provenance
+          npm run install:packages
+          npm run publish:packages -- --provenance
 
       - name: Publish Gradle plugin
         working-directory: gradle-plugin
@@ -44,5 +52,5 @@ jobs:
           GRADLE_PUBLISH_SECRET: ${{ secrets.GRADLE_PUBLISH_SECRET }}
         run: |
           chmod +x gradlew
-          ./gradlew publishPlugins
+          ./gradlew publish
 

.gitignore

@@ -12,8 +12,7 @@ gradle-app.setting
 !gradle-wrapper.jar
 *.class
 gradle.properties
-/gradle-plugin/bin/
-/example_plugin/bin/
+**/bin/
 
 # IDE
 .idea/
@@ -32,6 +31,9 @@ gradle.properties
 Thumbs.db
 desktop.ini
 
+# Code Graph index
+.codegraph/
+
 # Logs
 *.log
 logs/
@@ -40,7 +42,8 @@ logs/
 *.tsbuildinfo
 dist/
 
-# Test server runtime
+# Test server runtime — plugwright writes it under <testsDir>/generated/<environment>
+generated/
 run/
 test-server/
 **/server.properties
@@ -62,9 +65,6 @@ test-server/
 **/spigot.jar
 server.jar
 
-# Compiled test files
-**/e2e/dist/
-
 # Temporary files
 *.tmp
 *.temp
@@ -81,3 +81,9 @@ release.properties
 dependency-reduced-pom.xml
 
 .serena/
+
+# Publishing credentials for a private registry. See .env.example.
+.env
+
+# Local, per-developer notes kept beside the checked-in docs.
+*.local.md