repo maintenance (#749)

.github/ISSUE_TEMPLATE/1_verification-request.yml

@@ -1,12 +1,12 @@
 name: Plugin Verification Request
 description: Request verification for your plugin
-title: "Verification Request: homebridge-"
+title: 'Verification Request: homebridge-'
 labels:
   - pending
 body:
   - type: markdown
     attributes:
-      value: "## Basic Details"
+      value: '## Basic Details'
   - type: markdown
     attributes:
       value: >
@@ -37,13 +37,13 @@ body:
       required: false
   - type: markdown
     attributes:
-      value: "## Verification Requirements"
+      value: '## Verification Requirements'
   - type: markdown
     attributes:
-      value: "### General"
+      value: '### General'
   - type: markdown
     attributes:
-      value: "Please answer/confirm the following conditions:"
+      value: 'Please answer/confirm the following conditions:'
   - type: dropdown
     attributes:
       label: The plugin does not offer the same nor less functionality than that of
@@ -57,7 +57,7 @@ body:
       required: true
   - type: markdown
     attributes:
-      value: "## Environment"
+      value: '## Environment'
   - type: dropdown
     attributes:
       label: The plugin successfully installs and does not start unless it is
@@ -82,7 +82,7 @@ body:
       required: true
   - type: markdown
     attributes:
-      value: "## Codebase"
+      value: '## Codebase'
   - type: dropdown
     attributes:
       label: The plugin does not contain any analytics or calls that enable you to
@@ -118,7 +118,7 @@ body:
       required: true
   - type: markdown
     attributes:
-      value: "## More Information"
+      value: '## More Information'
   - type: textarea
     attributes:
       label: More Information

.github/ISSUE_TEMPLATE/2_icon-request.yml

@@ -1,10 +1,10 @@
 name: Plugin Icon Request
 description: Request an icon for your verified plugin
-title: "Plugin Icon Request: homebridge-"
+title: 'Plugin Icon Request: homebridge-'
 body:
   - type: markdown
     attributes:
-      value: "## Basic Details"
+      value: '## Basic Details'
   - type: markdown
     attributes:
       value: |

.github/workflows/check-json.yml → .github/workflows/check-json-files.yml

@@ -1,4 +1,4 @@
-name: Check JSON
+name: Check JSON Files
 on:
   push:
     branches:

.github/workflows/plugin-checks-request.yml

@@ -1,4 +1,4 @@
-name: Plugin Pre-Checks (Request)
+name: Plugin Checks (Request)
 on:
   workflow_dispatch:
     inputs:
@@ -17,11 +17,11 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event_name == 'issues' || (github.event_name == 'issue_comment' &&
       github.event.comment.body == '/check') || (github.event_name == 'workflow_dispatch' &&
-        inputs.plugin)
+      inputs.plugin)
     steps:
       - uses: actions/checkout@v4
-      - name: Install Dependencies
-        run: npm install --prefix precheck
+      - name: Install Dependencies & Build
+        run: npm install && npm run plugin-checks:build
       - name: Extract Plugin Name
         id: extract
         run: |
@@ -33,6 +33,6 @@ jobs:
           fi
           echo "PLUGIN_NAME=$PLUGIN_NAME" >> $GITHUB_ENV
       - name: Check Plugin
-        uses: ./precheck
+        uses: ./src/plugin-checks
         with:
           plugin: ${{ env.PLUGIN_NAME }}

.github/workflows/plugin-checks-schedule.yml

@@ -1,22 +1,22 @@
-name: Plugin Pre-Checks (Schedule)
+name: Plugin Checks (Schedule)
 on:
   workflow_dispatch:
   schedule:
-    - cron: "0 0,6,12,18 * * *"
+    - cron: '0 0,6,12,18 * * *'
 
 jobs:
   check-plugin:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Install Dependencies
-        run: npm install --prefix precheck
+      - name: Install Dependencies & Build
+        run: npm install && npm run plugin-checks:build
       - name: Randomly Select Plugin
         id: get-verified-plugin
         run: |
           echo "plugin=$(jq -r '.[]' verified-plugins.json | sed '/^$/d' | shuf -n 1)" >> $GITHUB_ENV
         shell: bash
       - name: Check Plugin
-        uses: ./precheck
+        uses: ./src/plugin-checks
         with:
           plugin: ${{ env.plugin }}

.github/workflows/maintain-tarballs.yml → .github/workflows/plugin-tarballs.yml

@@ -8,18 +8,15 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: ./tarballs
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: v20
-      - name: Install dependencies
-        run: npm install
-      - name: Maintain Tarballs
-        run: npm run maintain-tarballs
+      - name: Install Dependencies & Build
+        run: npm install && npm run plugin-tarballs:build
+      - name: Plugin Tarball Maintenance
+        run: npm run plugin-tarballs:run
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - uses: gautamkrishnar/keepalive-workflow@v2

.gitignore

@@ -2,3 +2,7 @@
 .DS_Store
 node_modules
 work
+src/**/*.js
+src/**/*.js.map
+src/**/*.d.ts
+test-area

README.md

@@ -71,6 +71,96 @@ You may optionally add one of the **Verified By Homebridge** badges to your plug
 
 If you decide you no longer wish to maintain your plugin, please reach out to the Homebridge team on the [Homebridge Discord](https://discord.gg/6GUFCb). We can assist in finding a new owner, or take over the repository until a new maintainer can be found.
 
+## Un-verification
+
+Your plugin may be subject to another review or be removed from the verification list when deemed necessary by the Homebridge team - this could be (but not limited to) the following scenarios:
+
+- We notice an increased amount of issues arising from your plugin, which results in a suboptimal experience for the user, for example, a Homebridge crash loop.
+- Your plugin has been unmaintained for some time, and a fork or new plugin offering improved functionality is created.
+
+We will generally do our best to contact existing developers of plugins before removing verification status. However, we may **immediately** remove verification status in the following (but not limited to) the following scenarios:
+
+- We notice any sort of user analysis tracking in a verified plugin
+- A new plugin requests verification which replaces the functionality of any existing plugin, and we notice that the existing plugin has not been maintained for an extended period of time (and we deem it likely that any contact attempt with the developer would be unsuccessful).
+
+## Verified Plugin Bundles
+
+The purpose of this is to help make the plugin installation process faster and more reliable for verified plugins.
+
+### Why This Is Needed
+
+Homebridge plugins are published and distributed to the NPM registry and installed using the `npm` cli tool.
+
+While `npm` works for the most part, later versions have become increasingly resource hungry and prone to failure on low powered devices with limited RAM and slow disk I/O (such as a Raspberry Pi).
+
+When using `npm` to install a plugin, it has to individually fetch the metadata, and download, verify and extract the tarball for every dependency a plugin has. This can result in hundreds of HTTP requests every time a plugin is installed or updated. An error during any of these operations will often result in the plugin failing to install or update.
+
+This project pre-bundles verified plugins, making them available to download, with all their dependencies, in a single tarball. Additionally, a SHA256 sum of the tarball is available so the integrity of the bundle can be verified after being downloaded to the user's system.
+
+A plugin installed via a bundle from this repo can be downloaded and installed in seconds, compared the minutes it might take for some plugins on the same hardware.
+
+### How The Bundle Generation Process Works
+
+Every 30 minutes, a job is executed using GitHub Actions to check for updates made to any [verified Homebridge plugins](https://homebridge.io/w/Verified-Plugins).
+
+Plugins that require updates are then:
+
+1. Installed using `npm` in a clean work directory, post install scripts are disabled;
+2. then a `.tar.gz` bundle is created for the plugin, including all it's dependencies;
+3. then a `.sha256` checksum file is generated for the bundle;
+4. finally the resulting tarball and checksum file are uploaded to the [Homebridge Plugin Repo](https://github.com/homebridge/plugin-repo/releases/tag/v1).
+
+The two most recent versions of a plugin are retained in the [Homebridge Plugin Repo](https://github.com/homebridge/plugin-repo/releases/tag/v1), older versions are purged automatically.
+
+### How Plugins Are Installed Via Bundles
+
+Bundles are only used on certain systems:
+
+* Debian-based Linux ([via apt package](https://github.com/homebridge/homebridge-apt-pkg)): requires apt package update (=>1.0.27)
+* Docker: requires image update (=>2022-07-07)
+* Synology DSM 7: requires package update via DSM Package Center (=>3.0.7)
+
+When a user requests a plugin to be installed or updated via the Homebridge UI the following workflow is executed:
+
+1. Check if running on a compatible system
+2. Check the plugin is verified
+3. Check if a download bundle is available for the requested version
+4. Download the `.sha256` checksum for the bundle
+5. Download the `.tar.gz` tarball
+6. Check the integrity of the tarball against the checksum
+7. Create a backup of the existing plugin installation (if already installed)
+8. Extract the tarball
+9. Run `npm rebuild` in the plugin's root directory to have any post install scripts executed locally
+10. Update the local `package.json` with the plugin and it's version
+
+If the extraction, or `npm rebuild` steps fail, the old version of the plugin will be restored.
+
+If at any step, the process fails, the Homebridge UI will fall back to using `npm` to complete the installation.
+
+### Download Statistics
+
+This project may impact the download stats for plugins provided by the NPM registry.
+
+As such download stats are available via the [download-statistics.json](https://github.com/homebridge/plugin-repo/releases/download/v1/download-statistics.json) file. This file contains the total downloads from this repo for each verified plugin, as well as the download count for each version (including old versions that have been purged).
+
+The `download-statistics.json` file is updated every 30 minutes.
+
+If you are accessing the file programmatically, you will need add a `nonce` query string to the URL to prevent it being redirected to an older (deleted) version of the file. E.g. `/download-statistics.json?nonce=1657193776`.
+
+### FAQ
+
+#### How do I get my plugin included?
+
+All [verified Homebridge plugins](https://homebridge.io/w/Verified-Plugins) are automatically included.
+
+#### What happens if a user attempts to install the latest version of my plugin before the bundle is created?
+
+The plugin will be installed directly from the NPM registry instead.
+
+#### How do I exclude my plugin from being bundled by this project?
+
+Create a pull request adding your plugin's name to the `pluginFilter: string[]` array in the [src/maintain-tarballs.ts](./src/plugin-tarballs.ts) file.
+
 ## Community
 
 The [#plugin-development](https://discord.gg/A7nCjbz) channel in the official Homebridge Discord server is where Homebridge plugin developers can get tips and advice from other developers and the Homebridge project team.
@@ -81,18 +171,14 @@ The [#plugin-development](https://discord.gg/A7nCjbz) channel in the official Ho
 
 </span>
 
-## Unverification
-
-Your plugin may be subject to another review or be removed from the verification list when deemed necessary by the Homebridge team - this could be (but not limited to) the following scenarios:
+## Credits
 
-- We notice an increased amount of issues arising from your plugin, which results in a suboptimal experience for the user, for example, a Homebridge crash loop.
-- Your plugin has been unmaintained for some time, and a fork or new plugin offering improved functionality is created.
+- Thanks to [@hjdhjd](https://github.com/hjdhjd) for the _for-the-badge_ style badge!
 
-We will generally do our best to contact existing developers of plugins before removing verification status. However, we may **immediately** remove verification status in the following (but not limited to) the following scenarios:
+## License
 
-- We notice any sort of user analysis tracking in a verified plugin
-- A new plugin requests verification which replaces the functionality of any existing plugin, and we notice that the existing plugin has not been maintained for an extended period of time (and we deem it likely that any contact attempt with the developer would be unsuccessful).
+Copyright (C) 2022-2024 oznu
 
-## Credits
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
 
-- Thanks to [@hjdhjd](https://github.com/hjdhjd) for the _for-the-badge_ style badge!
+This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the [GNU General Public License](./LICENSE) for more details.