docs: update docs

.envrc

@@ -1,12 +1,11 @@
-# export DEBUG="Eleventy:EleventyErrorHandler"
-export DEBUG="Eleventy:EleventyErrorHandler,11ty-plugin*"
+export DEBUG="Eleventy:EleventyErrorHandler,11ty-test-utils"
+# export DEBUG="Eleventy:EleventyErrorHandler,11ty-test-utils,11ty-plugin*"
 # export DEBUG="DevEleventy:*,Eleventy*"
-export ELEVENTY_ENV=development
 export NODE_ENV=production
 export NODE_DEBUG="script:*"
 export SKIP_TELEGRAM_MESSAGES=1
 
 # secrets exposed as environment variables
-export GOOGLE_APPLICATION_CREDENTIALS=/run/secrets/prj-kitchen-sink/sa-storage-uploader
+# export GOOGLE_APPLICATION_CREDENTIALS=/run/secrets/prj-kitchen-sink/sa-storage-uploader
 export PLAUSIBLE=$(cat /run/secrets/plausible/test_site)
 export TELEGRAM=$(cat /run/secrets/telegram/personal_bot)

.github/workflows/ci.yaml

@@ -13,13 +13,16 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest]
+        os: [ubuntu-latest, macos-latest]
+        # https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources
+        # os: [ubuntu-latest, macos-latest, windows-latest]
         # Test all packages with:
         # 1. Maintenance LTS
         # 2. Active LTS
         # 3. Current (i.e. the latest Node.js version available)
         # https://nodejs.org/en/about/previous-releases
-        node: ['lts/Hydrogen', 'lts/Iron', 'current']
+        node: [ lts/Iron]
+        # node: [lts/Hydrogen, lts/Iron, current]
         # https://www.npmjs.com/package/@11ty/eleventy?activeTab=versions
         eleventy: ['3.0.0-alpha.4']
     steps:
@@ -53,11 +56,12 @@ jobs:
 
       - name: 🔍 Test @jackdbd/eleventy-plugin-ensure-env-vars
         env:
+          DEBUG: Eleventy:EleventyErrorHandler,11ty-plugin*
           NODE_ENV: test
         run: npm run test:ci -w packages/eleventy-plugin-ensure-env-vars
 
-      - name: 🔍 Test @jackdbd/eleventy-plugin-permissions-policy
-        run: npm run test:ci -w packages/eleventy-plugin-permissions-policy
+      # - name: 🔍 Test @jackdbd/eleventy-plugin-permissions-policy
+      #   run: npm run test:ci -w packages/eleventy-plugin-permissions-policy
 
       - name: 🔍 Test @jackdbd/eleventy-plugin-telegram
         env:
@@ -66,8 +70,8 @@ jobs:
 
       - name: 🔍 Test @jackdbd/eleventy-plugin-text-to-speech
         env:
-          GOOGLE_APPLICATION_CREDENTIALS: ${{ secrets.GOOGLE_APPLICATION_CREDENTIALS }}
-          TELEGRAM: ${{ secrets.TELEGRAM }}
+          SA_JSON_KEY_STORAGE_UPLOADER: ${{ secrets.SA_JSON_KEY_STORAGE_UPLOADER }}
+          SA_JSON_KEY_TEXT_TO_SPEECH: ${{ secrets.SA_JSON_KEY_TEXT_TO_SPEECH }}
         run: npm run test:ci -w packages/eleventy-plugin-text-to-speech
 
       - name: ⬆️ Upload test coverage to Codecov

.github/workflows/release-to-npmjs.yaml

@@ -14,15 +14,14 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         # Use the Active LTS for this workflow
-        # https://nodejs.org/en/
-        # https://nodejs.org/en/about/releases/
-        node: ['16.17.0']
+        # https://nodejs.org/en/about/previous-releases
+        node: ['lts/Iron']
     steps:
       - name: 🛎️ Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: ⚙️ Set up Node.js ${{ matrix.node }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node }}
 

custom-types/11ty__eleventy/index.d.ts

@@ -1,10 +1,42 @@
 declare module '@11ty/eleventy' {
-  type TransformFn = (content: string, outputPath: string) => Promise<string>
+  /**
+   * Event names available in Eleventy plugins.
+   *
+   * @see [Events](https://www.11ty.dev/docs/events/)
+   */
+  export type EventName =
+    | 'eleventy.before'
+    | 'eleventy.after'
+    | 'eleventy.beforeWatch'
+
+  /**
+   * Object available in `eleventy.before` and `eleventy.after` event handlers.
+   *
+   * @see [Event Arguments](https://www.11ty.dev/docs/events/#event-arguments)
+   */
+  export interface EventArguments {
+    inputDir: string
+    dir: { input: string; includes: string; data: string; output: string }
+    runMode: 'build' | 'watch' | 'serve'
+    outputMode: 'fs' | 'json' | 'ndjson'
+    incremental: boolean
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    results?: any
+  }
+
+  type EventHandler = (arg: EventArguments) => void | Promise<void>
+
+  type TransformHandler = (
+    content: string,
+    outputPath: string
+  ) => string | Promise<string>
+
   export interface EleventyConfig {
     userConfig: any
     verbose: boolean
     addPlugin(pluginFn: () => void, pluginOptions: Object): Promise<void>
-    addTransform(name: string, fn: TransformFn): Promise<void>
+    addTransform(transformName: string, fn: TransformHandler): Promise<void>
+    on(eventName: EventName, fn: EventHandler): Promise<void>
   }
 
   interface Options {