Refactor code for readability, consistency, and modularity

.github/scripts/releaseAutomation.cjs

@@ -0,0 +1,72 @@
+const {spawnSync} = require("node:child_process");
+const path = require("node:path");
+
+const root = path.resolve(__dirname, "../..");
+
+const shouldRelease = env => {
+    if (env.GITHUB_REF !== "refs/heads/main" || !["push", "workflow_dispatch"].includes(env.GITHUB_EVENT_NAME)) {
+        return false;
+    }
+
+    const actor = env.GITHUB_ACTOR;
+    const appSlug = env.RELEASE_APP_SLUG;
+    if (!actor || !appSlug) {
+        throw new Error("Release actor and App slug are required.");
+    }
+
+    // The authenticated actor survives reruns; commit authors and messages can be spoofed.
+    return actor.toLowerCase() !== `${appSlug}[bot]`.toLowerCase();
+};
+
+const getReleaseArguments = env => {
+    // The policy job runs before npm ci, so load this dependency only for release arguments.
+    const {validRange} = require("semver");
+    const tag = env.RELEASE_NPM_TAG || "latest";
+    // release-it later passes ['--tag', tag] to npm, where a leading '--' could become another option.
+    if (!/^[a-zA-Z][a-zA-Z0-9._-]*$/.test(tag) || validRange(tag)) {
+        throw new Error("Invalid npm dist-tag.");
+    }
+
+    return [
+        "--ci",
+        ...(env.RELEASE_PREID ? [`--preRelease=${env.RELEASE_PREID}`] : []),
+        `--npm.tag=${tag}`,
+        ...(env.RELEASE_VERSION ? [`--increment=${env.RELEASE_VERSION}`] : []),
+    ];
+};
+
+const runRelease = (env = process.env, execute = spawnSync) => {
+    if (!shouldRelease(env)) {
+        throw new Error("This event is not allowed to release.");
+    }
+    if (env.RELEASE_TOKEN_APP_SLUG !== env.RELEASE_APP_SLUG) {
+        throw new Error("The release token App does not match RELEASE_APP_SLUG.");
+    }
+
+    const result = execute(
+        process.execPath,
+        [path.join(root, "node_modules/release-it/bin/release-it.js"), ...getReleaseArguments(env)],
+        {cwd: root, env, shell: false, stdio: "inherit"}
+    );
+    if (result.error) {
+        throw result.error;
+    }
+    return result.status ?? 1;
+};
+
+if (require.main === module) {
+    try {
+        if (process.argv[2] === "policy") {
+            process.stdout.write(`should_release=${shouldRelease(process.env)}\n`);
+        } else if (process.argv[2] === "run") {
+            process.exitCode = runRelease();
+        } else {
+            throw new Error("Expected policy or run.");
+        }
+    } catch (error) {
+        console.error(error.message);
+        process.exitCode = 1;
+    }
+}
+
+module.exports = {shouldRelease, getReleaseArguments, runRelease};

.github/scripts/validateMainPullRequestSource.mjs

@@ -0,0 +1,26 @@
+import {readFileSync} from "node:fs";
+
+try {
+    const event = JSON.parse(readFileSync(0, "utf8"));
+    const pullRequest = event?.pull_request;
+    const headRepositoryId = pullRequest?.head?.repo?.id;
+    const baseRepositoryId = pullRequest?.base?.repo?.id;
+    const allowed =
+        pullRequest?.base?.ref === "main" &&
+        pullRequest?.head?.ref === "develop" &&
+        Number.isSafeInteger(headRepositoryId) &&
+        headRepositoryId > 0 &&
+        Number.isSafeInteger(baseRepositoryId) &&
+        baseRepositoryId > 0 &&
+        headRepositoryId === baseRepositoryId;
+
+    if (allowed) {
+        console.log("Source policy passed: develop -> main in the same repository.");
+    } else {
+        console.error("Only pull requests from this repository's develop branch may target main.");
+        process.exitCode = 1;
+    }
+} catch {
+    console.error("Unable to read valid pull request event JSON.");
+    process.exitCode = 1;
+}

.github/workflows/ci.yml

@@ -7,6 +7,7 @@ on:
       - 'feature/**'
   pull_request:
     branches:
+      - main
       - develop
       - 'feature/**'
   workflow_call:
@@ -64,16 +65,27 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Set up Firefox
+        if: matrix.os == 'ubuntu-latest'
+        id: firefox
+        uses: browser-actions/setup-firefox@v1
+        with:
+          firefox-version: latest
+
       - name: Typecheck
         run: npm run typecheck
 
+      - name: Typecheck integration fixtures
+        run: npm run typecheck:integration
+
       - name: Test
         if: matrix.os == 'ubuntu-latest'
         run: npm run test:ci
         env:
           ADNBN_CHROME_BIN: ${{ steps.chrome.outputs.chrome-path }}
+          ADNBN_FIREFOX_BIN: ${{ steps.firefox.outputs.firefox-path }}
 
-      # The CDP extension-loading scenario is verified on Chrome's Linux runner.
+      # Chrome CDP and Firefox BiDi extension scenarios run on the Linux runner.
       # The rest of the test suite remains part of the full OS x Node matrix.
       - name: Test (non-browser)
         if: matrix.os != 'ubuntu-latest'

.github/workflows/main-pr.yml

@@ -0,0 +1,25 @@
+name: Main PR
+
+on:
+  pull_request_target:
+    branches:
+      - main
+    types: [opened, reopened, synchronize, edited]
+
+permissions:
+  contents: read
+
+jobs:
+  source-policy:
+    name: Main PR source (develop only)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout trusted policy
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          ref: ${{ github.workflow_sha }}
+          persist-credentials: false
+
+      - name: Validate pull request source
+        run: node .github/scripts/validateMainPullRequestSource.mjs < "$GITHUB_EVENT_PATH"

.github/workflows/release.yml

@@ -21,26 +21,63 @@ on:
         type: string
 
 permissions:
-  contents: write
-  id-token: write
+  contents: read
 
 jobs:
+  policy:
+    name: Release policy
+    if: >-
+      github.ref == 'refs/heads/main' &&
+      github.actor != format('{0}[bot]', vars.RELEASE_APP_SLUG)
+    runs-on: ubuntu-latest
+    outputs:
+      should_release: ${{ steps.policy.outputs.should_release }}
+    steps:
+      - name: Checkout trusted workflow revision
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.workflow_sha }}
+          persist-credentials: false
+
+      - name: Check release event
+        id: policy
+        env:
+          RELEASE_APP_SLUG: ${{ vars.RELEASE_APP_SLUG }}
+        run: node .github/scripts/releaseAutomation.cjs policy >> "$GITHUB_OUTPUT"
+
   ci:
     name: CI
+    needs: policy
+    if: needs.policy.outputs.should_release == 'true'
     uses: ./.github/workflows/ci.yml
     with:
       full: true
 
   release:
     name: Release & Publish
     runs-on: ubuntu-latest
-    needs: ci
+    needs: [policy, ci]
+    if: needs.policy.outputs.should_release == 'true'
+    environment: release
+    permissions:
+      contents: write
+      id-token: write
     steps:
+      - name: Create release App token
+        id: release-app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ vars.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+          # Omitting owner/repositories scopes the token to this repository only.
+          permission-contents: write
+
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
           fetch-tags: true
+          token: ${{ steps.release-app-token.outputs.token }}
 
       - name: Use Node.js
         uses: actions/setup-node@v4
@@ -65,26 +102,13 @@ jobs:
         env:
           DEBUG: release-it:*,@release-it/*
           HUSKY: 0
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          VERSION_ARG=""
-          if [ -n "${{ inputs.version }}" ]; then
-            VERSION_ARG="${{ inputs.version }}"
-          fi
-
-          PREID_ARG=""
-          if [ -n "${{ inputs.preid }}" ]; then
-            PREID_ARG="--preRelease=${{ inputs.preid }}"
-          fi
-
-          if [ -n "${{ inputs.npm_tag }}" ]; then
-            NPM_TAG="${{ inputs.npm_tag }}"
-          else
-            NPM_TAG="latest"
-          fi
-          NPM_TAG_ARG="--npm.tag=${NPM_TAG}"
-
-          npx release-it --ci $PREID_ARG $NPM_TAG_ARG $VERSION_ARG
+          GITHUB_TOKEN: ${{ steps.release-app-token.outputs.token }}
+          RELEASE_APP_SLUG: ${{ vars.RELEASE_APP_SLUG }}
+          RELEASE_TOKEN_APP_SLUG: ${{ steps.release-app-token.outputs.app-slug }}
+          RELEASE_VERSION: ${{ inputs.version }}
+          RELEASE_PREID: ${{ inputs.preid }}
+          RELEASE_NPM_TAG: ${{ inputs.npm_tag }}
+        run: node .github/scripts/releaseAutomation.cjs run
 
       - name: Sync main → develop
         uses: devmasx/merge-branch@v1.4.0
@@ -95,4 +119,3 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
         env:
           HUSKY: 0
-

.gitignore

@@ -19,6 +19,6 @@ TODOs.md
 stats.html
 .tool-versions
 .cache
-/tests/integration/browser/offscreen-service/.adnbn/
+/tests/integration/**/.adnbn/
 *-stats.txt
 .npmrc

.prettierignore

@@ -1,7 +1,7 @@
 node_modules/
 .github/workflows/
 dist/
-build/
+/build/
 addon/
 src/cli/entrypoint/file/tests/fixtures/
-CHANGELOG.md
+CHANGELOG.md

.release-it.cjs

@@ -180,7 +180,7 @@ const createReleaseConfig = () => {
         git: {
             requireCleanWorkingDir: true,
             requireUpstream: false,
-            requireBranch: false,
+            requireBranch: "main",
             commit: true,
             commitMessage: "chore(release): v${version}",
             tag: true,