chore: merge plugin template

.cspell.json

@@ -1,10 +1,28 @@
 {
  "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
  "version": "0.2",
- "ignorePaths": ["**/*.json", "**/*.css", "node_modules", "**/*.log"],
+ "ignorePaths": ["**/*.json", "**/*.css", "node_modules", "**/*.log", "./src/adapters/supabase/**/**.ts"],
  "useGitignore": true,
  "language": "en",
- "words": ["dataurl", "devpool", "outdir", "servedir"],
+ "words": [
+ "Nektos",
+ "dataurl",
+ "devpool",
+ "outdir",
+ "servedir",
+ "Supabase",
+ "SUPABASE",
+ "typebox",
+ "ubiquibot",
+ "Smee",
+ "typeguards",
+ "mswjs",
+ "Typeguards",
+ "sonarjs",
+ "knip",
+ "mischeck"
+ ],
+
  "dictionaries": ["typescript", "node", "software-terms"],
  "import": ["@cspell/dict-typescript/cspell-ext.json", "@cspell/dict-node/cspell-ext.json", "@cspell/dict-software-terms"],
  "ignoreRegExpList": ["[0-9a-fA-F]{6}"]

.dev.vars.example

@@ -0,0 +1 @@
+MY_SECRET="MY_SECRET"

.github/knip.ts

@@ -6,7 +6,7 @@ const config: KnipConfig = {
  ignore: ["src/types/config.ts", "**/__mocks__/**", "**/__fixtures__/**"],
  ignoreExportsUsedInFile: true,
  // eslint can also be safely ignored as per the docs: https://knip.dev/guides/handling-issues#eslint--jest
- ignoreDependencies: ["eslint-config-prettier", "eslint-plugin-prettier", "@types/jest", "@mswjs/data"],
+ ignoreDependencies: ["eslint-config-prettier", "eslint-plugin-prettier", "@mswjs/data"],
  eslint: true,
 };
 

.github/workflows/compute.yml

@@ -0,0 +1,44 @@
+name: "the name of the plugin"
+
+on:
+ workflow_dispatch:
+ inputs:
+ stateId:
+ description: "State Id"
+ eventName:
+ description: "Event Name"
+ eventPayload:
+ description: "Event Payload"
+ settings:
+ description: "Settings"
+ authToken:
+ description: "Auth Token"
+ ref:
+ description: "Ref"
+
+jobs:
+ compute:
+ name: "plugin name"
+ runs-on: ubuntu-latest
+ permissions: write-all
+ env:
+ SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
+ SUPABASE_KEY: ${{ secrets.SUPABASE_KEY }}
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: setup node
+ uses: actions/setup-node@v4
+ with:
+ node-version: "20.10.0"
+
+ - name: install dependencies
+ run: yarn
+
+ - name: execute directive
+ run: npx tsx ./src/main.ts
+ id: plugin-name
+ env:
+ SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
+ SUPABASE_KEY: ${{ secrets.SUPABASE_KEY }}

.github/workflows/knip-reporter.yml

@@ -6,6 +6,8 @@ on:
  types:
  - completed
 
+permissions: write-all
+
 jobs:
  knip-reporter:
  runs-on: ubuntu-latest

.github/workflows/knip.yml

@@ -2,6 +2,7 @@ name: Knip
 
 on:
  pull_request:
+ workflow_dispatch:
 
 jobs:
  run-knip:
@@ -10,10 +11,6 @@ jobs:
  - name: Checkout
  uses: actions/checkout@v4
 
- # needed to use yarn v4
- - name: Enable corepack
- run: corepack enable
-
  - name: Setup Node
  uses: actions/setup-node@v4
  with:

.github/workflows/worker-delete.yml

@@ -0,0 +1,44 @@
+name: Delete Deployment
+
+on:
+ delete:
+
+jobs:
+ delete:
+ runs-on: ubuntu-latest
+ name: Delete Deployment
+ steps:
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version: "20.10.0"
+
+ - name: Enable corepack
+ run: corepack enable
+
+ - uses: actions/checkout@v4
+
+ - name: Get Deleted Branch Name
+ id: get_branch
+ run: |
+ branch_name=$(echo '${{ github.event.ref }}' | sed 's#refs/heads/##' | sed 's#[^a-zA-Z0-9]#-#g')
+ echo "branch_name=$branch_name" >> $GITHUB_ENV
+ - name: Retrieve and Construct Full Worker Name
+ id: construct_worker_name
+ run: |
+ base_name=$(grep '^name = ' wrangler.toml | head -n 1 | sed 's/^name = "\(.*\)"$/\1/')
+ full_worker_name="${base_name}-${{ env.branch_name }}"
+ # Make sure that it doesnt exceed 63 characters or it will break RFC 1035
+ full_worker_name=$(echo "${full_worker_name}" | cut -c 1-63)
+ echo "full_worker_name=$full_worker_name" >> $GITHUB_ENV
+ - name: Delete Deployment with Wrangler
+ uses: cloudflare/wrangler-action@v3
+ with:
+ apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+ accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+ command: delete --name ${{ env.full_worker_name }}
+
+ - name: Output Deletion Result
+ run: |
+ echo "### Deployment URL" >> $GITHUB_STEP_SUMMARY
+ echo 'Deployment `${{ env.full_worker_name }}` has been deleted.' >> $GITHUB_STEP_SUMMARY

.github/workflows/worker-deploy.yml

@@ -0,0 +1,50 @@
+name: Deploy Worker
+
+on:
+ push:
+ workflow_dispatch:
+
+jobs:
+ deploy:
+ runs-on: ubuntu-latest
+ name: Deploy
+ steps:
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version: "20.10.0"
+
+ - name: Enable corepack
+ run: corepack enable
+
+ - uses: actions/checkout@v4
+
+ - name: Update wrangler.toml Name Field
+ run: |
+ branch_name=$(echo '${{ github.event.ref }}' | sed 's#refs/heads/##' | sed 's#[^a-zA-Z0-9]#-#g')
+ # Extract base name from wrangler.toml
+ base_name=$(grep '^name = ' wrangler.toml | head -n 1 | sed 's/^name = "\(.*\)"$/\1/')
+ # Concatenate branch name with base name
+ new_name="${base_name}-${branch_name}"
+ # Truncate the new name to 63 characters for RFC 1035
+ new_name=$(echo "$new_name" | cut -c 1-63)
+ # Update the wrangler.toml file
+ sed -i '0,/^name = .*/{s/^name = .*/name = "'"$new_name"'"/}' wrangler.toml
+ echo "Updated wrangler.toml name to: $new_name"
+ - name: Deploy with Wrangler
+ id: wrangler_deploy
+ uses: cloudflare/wrangler-action@v3
+ with:
+ apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+ accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+ secrets: |
+ SUPABASE_URL
+ SUPABASE_KEY
+ env:
+ SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
+ SUPABASE_KEY: ${{ secrets.SUPABASE_KEY }}
+
+ - name: Write Deployment URL to Summary
+ run: |
+ echo "### Deployment URL" >> $GITHUB_STEP_SUMMARY
+ echo "${{ steps.wrangler_deploy.outputs.deployment-url }}" >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -110,7 +110,12 @@ node_modules
 .pnp.cjs
 .pnp.loader.mjs
 .env
+.env.dev
+.dev.vars
 static/dist
 coverage
 junit.xml
 cypress/screenshots
+script.ts
+.wrangler
+test-dashboard.md

.husky/pre-commit

@@ -1 +1 @@
-bun run lint-staged
+bun run lint-staged

README.md

@@ -304,3 +304,95 @@ sync-branch-to-template() {
  # git remote remove template
 }
 ```
+# `@ubiquity-os/plugin-template`
+
+## Prerequisites
+
+- A good understanding of how the [kernel](https://github.com/ubiquity/ubiquibot-kernel) works and how to interact with it.
+- A basic understanding of the Ubiquibot configuration and how to define your plugin's settings.
+
+## Getting Started
+
+1. Create a new repository using this template.
+2. Clone the repository to your local machine.
+3. Install the dependencies preferably using `yarn` or `bun`.
+
+## Creating a new plugin
+
+- If your plugin is to be used as a slash command which should have faster response times as opposed to longer running GitHub action tasks, you should use the `worker` type.
+
+1. Ensure you understand and have setup the [kernel](https://github.com/ubiquity/ubiquibot-kernel).
+2. Update [compute.yml](./.github/workflows/compute.yml) with your plugin's name and update the `id`.
+3. Update [context.ts](./src/types/context.ts) with the events that your plugin will fire on.
+4. Update [manifest.json](./manifest.json) with a proper description of your plugin.
+5. Update [plugin-inputs.ts](./src/types/plugin-inputs.ts) to match the `with:` settings in your org or repo level configuration.
+
+- Your plugin config should look similar to this:
+
+```yml
+plugins:
+ - name: hello-world
+ id: hello-world
+ uses:
+ - plugin: http://localhost:4000
+ with:
+ # Define configurable items here and the kernel will pass these to the plugin.
+ configurableResponse: "Hello, is it me you are looking for?"
+ customStringsUrl: "https://raw.githubusercontent.com/ubiquibot/plugin-template/development/strings.json"
+```
+
+###### At this stage, your plugin will fire on your defined events with the required settings passed in from the kernel. You can now start writing your plugin's logic.
+
+6. Start building your plugin by adding your logic to the [plugin.ts](./src/plugin.ts) file.
+
+## Testing a plugin
+
+### Worker Plugins
+
+- `yarn/bun worker` - to run the worker locally.
+- To trigger the worker, `POST` requests to http://localhost:4000/ with an event payload similar to:
+
+```ts
+await fetch("http://localhost:4000/", {
+ method: "POST",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ stateId: "",
+ eventName: "",
+ eventPayload: "",
+ settings: "",
+ ref: "",
+ authToken: "",
+ }),
+});
+```
+
+A full example can be found [here](https://github.com/ubiquibot/assistive-pricing/blob/623ea3f950f04842f2d003bda3fc7b7684e41378/tests/http/request.http).
+
+#### Deploying the Worker
+For testing purposes, the worker can be deployed through the Worker Deploy and Worker Delete workflows. It requires to
+create a personal [Cloudflare Account](https://www.cloudflare.com/), and fill the `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` within your
+GitHub Action Secrets.
+
+### Action Plugins
+
+- Ensure the kernel is running and listening for events.
+- Fire an event in/to the repo where the kernel is installed. This can be done in a number of ways, the easiest being via the GitHub UI or using the GitHub API, such as posting a comment, opening an issue, etc in the org/repo where the kernel is installed.
+- The kernel will process the event and dispatch it using the settings defined in your `.ubiquibot-config.yml`.
+- The `compute.yml` workflow will run and execute your plugin's logic.
+- You can view the logs in the Actions tab of your repo.
+
+[Nektos Act](https://github.com/nektos/act) - a tool for running GitHub Actions locally.
+
+## More information
+
+- [Full Ubiquibot Configuration](https://github.com/ubiquity/ubiquibot/blob/0fde7551585499b1e0618ec8ea5e826f11271c9c/src/types/configuration-types.ts#L62) - helpful for defining your plugin's settings as they are strongly typed and will be validated by the kernel.
+- [Ubiquibot V1](https://github.com/ubiquity/ubiquibot) - helpful for porting V1 functionality to V2, helper/utility functions, types, etc. Everything is based on the V1 codebase but with a more modular approach. When using V1 code, keep in mind that most all code will need refactored to work with the new V2 architecture.
+
+## Examples
+
+- [Start/Stop Slash Command](https://github.com/ubq-testing/start-stop-module) - simple
+- [Assistive Pricing Plugin](https://github.com/ubiquibot/assistive-pricing) - complex
+- [Conversation Rewards](https://github.com/ubiquibot/conversation-rewards) - really complex